aspose file tools*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Javadoc documentation?? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Spring in Action this week in the Spring forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Javadoc documentation??" Watch "Javadoc documentation??" New topic
Author

Javadoc documentation??

Bruce Xu
Greenhorn

Joined: Feb 09, 2006
Posts: 7
hey,ranchers:
Do we need to generate the javadoc documentation for private classes and methods?
In my B&S specification, it says:
-------------------------------------------
...
Awkward or complex code should have descriptive comments, and javadoc style comments must be used for each element of the public interface of each class. You must create a full suite of documentation for the classes of the completed project. This must be generated using the tool "javadoc" and must be in HTML format. Provide javadoc documentation for all classes you write.
...
------------------------------------------

and it also says:
------------------------------------------
A subdirectory called javadoc, containing HTML/Javadoc documentation for all classes and interfaces you are submitting.
------------------------------------------

thanks in advance
Jeroen T Wenting
Ranch Hand

Joined: Apr 21, 2006
Posts: 1847
It's not stricly required, but I do write it anyway.

I write Javadoc for pretty much everything (including some class member variables) and have ANT set to generate for protected and more public only.

That should suffice the requirements (in fact it goes over them) as well as showing best practice (and working for the maintainability of the code, which depends on good documentation and coding style, which IMO includes complete developer documentation of private methods as well).

For the Javadoc style to follow, read the style guides and the JDK Javadoc.
There are conventions to be followed for things like the order in which exceptions are listed in Javadoc comments for example, which I'd not seen before.


42
 
It is sorta covered in the JavaRanch Style Guide.
 
subject: Javadoc documentation??