Javadoc overview

Javadoc is how Sun documents in the core application programming interface (API) of Java (see http://java.sun.com/javase/6/docs/api/), and how you can document the APIs you provide to other software developers. Javadoc output is HTML, with a navigation frame and a content frame. The javadoc utility extracts documentation from source code file javadoc comments placed immediately above the following:

Note: It would not make sense to publish private members. The default (undeclared) visibility, which is neither public nor protected, is also NOT used for javadoc.

Example of javadoc

  1. Download the zip that has an example of javadoc for two packages:
  2. Read the ReadMe in the zip.

Steps to run this javadoc
1. cd to the directory when you unzipped the archive, for example,
    D:\_08summer\javadoc-stuff
2. compile from above the packages
    javac demojavadoc\*.java
    javac mypack\*.java
3. Run the app
    java demojavadoc.JavadocDemo
4. Run javadoc for BOTH packages, using -d before the directory name to hold the HTML output
    javadoc -version -author -d output2 demojavadoc\*.java mypack\*.java
5. View the output in an HTML browser:
    file:///D:/_08summer/javadoc-stuff/index.html

javadoc - Adding javadoc to Your Source Code

Javadoc comments begin with /** and end with */

There are special tags, starting with @, for documenting a parameter, return value, and other items.

This class description includes HTML tags, which are optional.


 

This method description documents the parameters and return value.

 

This method description indicates that this method (or method signature) is obsolete in the current version.



javadoc - Generating the HTML Output

 

  1. Create a directory for your Java source code (.java files). In this example, the source code files are inside a directory called groovy, and the source code says that each class belongs to the groovy  package.
  2. Create a separate directory for your javadoc output (.html files), such as output-groovy.

  1. Create a package summary file.
    javadoc requires that it be named package-info.java and that it be in the same directory as your source code files.
  2. Put a summary comment about the package in the package summary file.

/**
* The groovy package is a set of examples that
* illustrate the use of javadoc tags.
* Note: This package summary, like ALL package
* summaries, must be in a file named
* <code>package-info.java</code>
* @version 1.1
* @author Your Name
*/
package groovy;

  1. Navigate one directory above the source code directory (from the groovy directory, cd .. at the command prompt).

    D:\__07Fall\9\javadoc>
     
  2. Compile all the classes in the directory,

    javac groovy/*.java
     
  3. Navigate to the directory that contains the source code files.

    cd groovy
     
  4. Run javadoc.

    javadoc -version -author -d D:\__07Fall\9\javadoc\output-groovy *.java

    Note: -version and -author tells javadoc to include the version number and author name(s), and -d specifies the directory for the HTML output.
    So the syntax is:
        javadoc   option(s)   directory_for_output    location_of_files_with_javadoc_comments
     
  5. Open the index.html file:

10. Verify that the package summary and author names appear.

I will run an example where I first cd to 

D:\_08summer\javadoc-stuff\zip_of_examples\javadoc

and then give this command

javadoc -version -author -d myOutput groovy\*.java

For More Information