Project Idea: Was Re: Convert String to Object - Newbie Question
Roedy Green wrote:
On Tue, 02 Oct 2007 03:11:42 -0700, Marion <mchew02@hotmail.com>
wrote, quoted or indirectly quoted someone who said :
I tried really hard to read the Java docs on the syntax of their
commands, yep very hard.
It gets easier over time as you get the hang of their way of
expressing.
Further you get to know what to EXPECT since they repeat the same
patterns in the UI.
My main complaint with Javadoc is the overwhelm. There is no
distinction between a method every program has to use and one almost
nobody will ever use. We need to assign a "learning index" to each
package, class, and method, and a tool to display in sorted order to
help you find the important stuff first.
The number is a relative importance number to other methods in the
same class.
Maybe you should add that to your list of projects.
I would like to see it done at both the class level and the
method/constructor level. A package may contain both classes that are
essential to any use of the package, and ones that are only needed in
some advanced cases.
The project could be split into two parts:
1. A doclet that would use order or different fonts or colors to show
the important features, based on e.g. annotations.
2. An automatic annotator that would survey a body of code and count
uses of classes and methods.
Obviously, it does not necessarily have to be literally annotations in
the code. It might be better to use a separate file for the importance
data. That way, an instructor could prepare special versions of the API
documentation that would emphasize the material students need for a
particular course.
Patricia