Introduction to Javadoc

Jussi Pohjolainen

Tampere Polytechnic University of Applied Sciences » ICT

Intro to Javadoc

• Javadoc is a tool that generates html documentation from comments in your code.
• Generated documentation is similar to Java API html documentation
• See Example of generated Javadoc documentation

Writing Javadoc comments

• Javadoc comment must precede
  • Class
  • Field
  • Constructor or
  • Method declaration
• Javadoc comment begins with /** and ends */
• Javadoc produces html-documentation, so you can put html-tags inside your comments
• Example:

  /**
  * This is my comment. You can add <strong>html tags</strong>.
  */
  

Special block tags

• Javadoc comment is divided into two parts: a description followed by block tags.
• Descriptions first sentence should be a summary sentence.
• Block tags (keep this order!) starts with letter @

  
  * @param       (classes, interfaces, methods and constructors only)
  * @return      (methods only)
  * @exception   (@throws is a synonym added in Javadoc 1.2)
  * @author      (classes and interfaces only, required)
  * @version     (classes and interfaces only, required. See footnote 1)
  * @see         
  * @since       
  * @serial      (or @serialField or @serialData)
  * @deprecated  (see How and When To Deprecate APIs)
  
  

Example: Javadoc comment

• See source code of Circle.java
  

  
     /**
     * Set circle's radius.
     *
     * @param r Circle's radius
     * @throws RuntimeException If given radius < 0
     */
     public void setRadius(double r) throws RuntimeException {
          if(r >= 0) {
              radius = r;
          }
          else
             throw new RuntimeException("Radius cannot be negative!");
     }
  

Example: Javadoc documentation

• Command: javadoc -d documentation *.java
• See the whole javadoc produced html-documentation
• Result is like this (in html):
  

• public void setRadius() throws java.lang.RuntimeException
  

  Set circle's radius.

  Parameters:

  Circle's radius

  Throws:

  java.lang.Exception - If given radius < 0

Detailed information

• More detailed information can be found from Sun's tutorials
• How to Write Doc Comments for the JavaDoc tool