Re: I'm looking for someone to appraise my java code for me..
travel2light wrote:
Is there a reason
for using JavaDoc comments instead of normal comments? I see JavaDoc
all the time in the documentation, but I've never understood the
advantage of creating my own.
Remember when you said,
I already discovered the importance of comments the hard way! I've
been revisiting some projects I started a long time ago and I've been
having a terrible time trying to make sense of them.
?
When you design a class to be used, that is, when you design a class as an
API, you take on responsibilities to the programmers and classes that use your
API. These responsibilities imbue an attitude of anal-retentive commenting,
documenting and testing of one's API before subjecting it to the abuse its
users shall surely heap upon it.
One way to facilitate a happy experience for API consumers is to provide
documentation of the API, external to the source code - a distillation of the
API's public and protected members and methods, what they're for and how to
use them. It would be especially nice if such API documentation were as
thoroughly organized and interlinked as Sun's own API docs,
<http://java.sun.com/javase/6/docs/api/>
It would be almost magically delicious if generation of such documents could
be automated through some tool that would, let's say, scan your source for
specially formatted comments on classes and their protected or public members,
then emit such beautiful, browsable pages in nice HTML, with fine control over
package-level comments, headers, footers and all that rot. You'd have it lift
all comments that began with, say, /** (slash, asterisk, asterisk), so it
would work as a normal comment but be special to your documentation tool.
Now your source becomes "literate programming" - compilable, self-documenting
artifacts. You get the visible part of the comments independently of the
source via the special Java documentation.
Let's call this special Java documentation magic tool "javadoc", and its
special magic comment format "javadoc comments".
<http://java.sun.com/javase/6/docs/technotes/tools/solaris/javadoc.html>
<http://java.sun.com/javase/6/docs/technotes/tools/windows/javadoc.html>
--
Lew