Good Javadoc use
Javadoc is a tool that you have in your %JAVA_HOME%\bin (Windows) or $JAVA_HOME/bin (UNIX) directory. It is being used to extract API documentation from your Java source code, into HTML.
Most IDEs fully support Javadoc. They assist the developer in writing, displaying and generating the Javadoc documentation. Javadoc is part of the development lifecycle. Good and up-to-date Javadoc is a sign of a healthy project.
API Users
The worst thing an API user can do is to ignore Javadoc. Having an easily accessible, local copy of the Javadoc for the library you are working with (Spring, Hibernate, Lucene etc) is the only way to work efficiently. Vast amounts of time have been put into compiling quality documentation for these libraries. Not using it will only slow you down.
Development Teams
One of the worst Netbeans feature is that it allows you to collapse all comments and even set this as the default behavior when opening a source file. Team members, working in the same piece of code, can no longer see the documentation written by other developers.
I actually had a developer asking me about what one of my methods did. For a moment I was confused and asked him whether I had written poor documentation. He then told me that he didn’t know that there was any Javadoc for that method. I don’t (want to) know whether Javadoc hiding is a feature of Netbeans or is a plugin, but that was definitely one of the most ineffective behaviors I’ve seen in a development team.
API designers
Writing good Javadoc involves many things which are documented by SUN. The general idea is that you don’t want to expose the implementation of the method through the documentation. API users will not care how you do it, but only what (and maybe why) you do.
So the following comment is bad:
/**
* This method uses StringBuffer to merge the name with surname and return
* the person's full name
*/
public String getFullName() {
A better version is:
/**
* Returns the full name of the Person. Will return "Nick Cave" if
* firstname is "Nick" and lastname is "Cave".
*
* @return the full name of the Person
*/
public String getFullName() {
Conclusion
We (Java developers) are very lucky that documentation is so tightly integrated with the language. Not using it though, takes all this goodness away.
July 31st, 2007 at 20:38
Αν και microsoft developer, ο ίδιος, πάντα μου άρεσε το πόσο καλά δομημένο και λειτουργικό εργαλείο είναι το javadoc. Είναι κρίμα που δεν διαθέτουμε λίγο παραπάνω χρόνο να γράφουμε καλό documentation με τον κώδικά μας…
Για τους microsoftαδες υπάρχει το Sandcastle (νομίζω της microsoft)
http://www.sandcastledocs.com/Wiki%20Pages/Home.aspx
και το open source Ndoc
http://ndoc.sourceforge.net/
Αυτά έχω χρησιμοποιήσει και είναι αρκετά καλά.
August 23rd, 2007 at 11:17
If you want to have a nice Javadoc API as the one of JDK, ie. with the packages on the upper left, all classes on lower left etc. then I use the following script to create my Javadoc:
Save the above to a .bat or .cmd or .sh file in the top directory of your application, e.g. where folder app is, if app is the name of the root package of your application.
You also need a packages.txt file in the same directory which contains the names of all the packages of your application one per line, i.e. in the form:
app
app.db
app.io
app.io.ui
app.help
etc.
Inside each package you must have a package.html file with the following ingredients:
Here you modify the title and the body. You must add a package.html to every package and sub-package of your application.
I know it is a lot of work, but Voila.
August 23rd, 2007 at 20:23
Yep, package.html is nice.
Thanks!