Two Laptop Bag*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes JavaDoc include private? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "JavaDoc include private?" Watch "JavaDoc include private?" New topic
Author

JavaDoc include private?

Matt Ghiold
Ranch Hand

Joined: Feb 24, 2002
Posts: 213
Hey guys,
Are you submitting your javadocs showing private members and methods or just public?
Thanks


-Matt<br /> SCJP2<br /> SCJD
Daniela Ch
Ranch Hand

Joined: Dec 13, 2002
Posts: 96
In my assignment they asked for the public interface only...
but dont be lazy and javadoc everything...
Peter den Haan
author
Ranch Hand

Joined: Apr 20, 2000
Posts: 3252
I would suggest javadoccing everything, but not necessarily generating javadoc documentation for everything.
The first question you should be asking yourself is: who is the audience for these javadocs? My assumption was at the time that the primary audience for the javadocs are developers writing new code against your classes.
Generating Javadocs for public methods only is a bad idea. Why? Unless you make your classes final, developers can create subclasses of your classes and gain access to protected methods. So your minimum documentation level should be for public and protected methods.
Given the audience assumption above, generating Javadocs for all methods, including private ones, is also a bad idea. Why? Because external code can't get at private methods anyway. Documenting them introduces a lot of unnecessary information into the docs that only serves to clutter up and confuse. Private methods are only interesting for developers working on the class itself, and they already have the source code including the javadocs in front of them; if that's not enough for them, they should be capable enough to generate full docs themselves.
This leaves the decision whether to include package-private methods or not. This depends on whether you think your audience will be developing further classes in the same package(s) or not.
- Peter
 
It is sorta covered in the JavaRanch Style Guide.
 
subject: JavaDoc include private?
 
Similar Threads
WA #1.....word association
How come public and friendly(default) access is allowed for top level class but not
displaying tag in jsp
Bullet-proof Class
What is the difference between these statements