Re: Javadoc is not for beginners
Thomas Adrian wrote:
Thank you all for replying,
- If javadoc is just a reference, it should be renamed to javaref
It's an automatic documentation generator for Java; doc is a
commonly-accepted abbreviation for documentation, and the concatenation
of Java and doc is Javadoc, hence the origin of its name.
- My point here is that it is very difficult to understand how to
implement certain classes by just lookung at the javadoc.
Implement or use? The purpose of the documentation is to provide
specific, per-instance detailed semantics of classes, methods, packages,
etc. These are the reasons when I use the Javadoc APIs, roughly ordered
by how often I use them for that reason:
1. What is the signature of method XYZ?
2. How do I use class XYZ to do foobar?
3. Can class XYZ do foobar?
4. Which package is class XYZ in? (I am ashamed to admit this...)
5. What can class XYZ do?
If you think that Javadoc is hard to understand, try reading some of the
Windows API documentation or Linux man pages for libraries or functions.
I have seen points where the only documentation was to look at the code
and figure out what exactly it was doing. Annoying when you're trying to
figure out whether or not you have to free a char* you pass in.
- Javadoc is based on what the developer choose to include in the
sourcecode, So Sun should really concider improving the javadoc and
make it more userfriendly. It could be made much better by just
including a few statement on the top of the javadoc page.
Sun's Java APIs are amazingly well-detailed, much more so than some of
the other documentations I've come across. In addition, I've found it a
lot more user-friendly than other types of documentation. MSDN is
annoying to go through quickly, and man pages equally so.
- Really, how many of you do not google the class you are about to
implement ?
Well, the only classes I've ever had to implement were the callback
interfaces and parts of the W3C DOM specification, so I can't really
say. The only class I've had to google to use, though, was ClassLoader,
although that was more a function of the fact that class-loading I've
found rather underspecified in Java.
- A lot of classes out there is not made by Sun , so they may not be
googable.
And the provider doesn't provide a tutorial/quickstart/comprehensive
Javadoc? Besides, documentation is only as good as the developer who
wrote it.
--
Beware of bugs in the above code; I have only proved it correct, not
tried it. -- Donald E. Knuth