How does one use the automatic documentation facility in java?

     /**
      * Computes the max of two integers
      *
      * @param x an integer
      * @param y another integer
      * @return the larger of the two integers
      */
     public static int max(int x, int y){
      if (x > y) return x;
      else return y;
     } 

1. The comment immediately precedes the method.
2. The comment begins with an extra asterisk, (/**) instead of (/*). It tells javadoc that this is a "documentation comment".
3. Subsequent lines must begin with an asterisk. Note that the comment ends in the usual way (with */).
4. The first line of comment tells us the purpose of this method.
5. This is followed by a blank line (containing only an *).
6. Each parameter in the method is introduced by the string "@param ", followed by its description. This may be omitted if there are no parameters.
7. The return value is introduced by the string "@return". This may be omitted if there is no return value.
8. In fact it is a good idea to write these comments first, even before you write one line of code.
9. Just do this exercise mechanically, even if the comments seem obvious -- at worst, your comments are unnecessary. But this is better than spending time pondering whether to write or not to write documentation comment for a method.
10. Finally, from the command shell in unix (or the command prompt in windows) issue the command

    		% javadoc MyProg.java
    

    This will produce a file called MyProg.html, which can be viewed by a browser. Indeed, if you know HTML, you can embed HTML tags directly into the comments (to specify fonts or include images, for instance). Other html files will also produced.
11. To view the output of javadoc, aim your browser at the current directory, and click on the html files.
12. Other tags:
    • @author
    • @version
    • @deprecated
    • @exception (@throws is a synonym in Javadoc 1.2)
13. Insertion of html commands and images directly into your javadoc comments may be useful.
14. Note that the images used in the html document shows up as ``broken images''. That is O.K., but all the images you need can be found in this image directory
15. More information?
    • Our T.A. Been's Javadoc notes (Local Copy)
    • From Sun's Javadoc Homepage.