How do you document the programming

11.3 Documentation of Java programs (javadoc)

The documentation of methods, variables and classes is part of the language and is supported by standard JDK tools.

The exact specifications for documenting Java classes are described in the Oracle document "Requirements for Writing Java API Specifications". You can also document your own Java classes according to these guidelines. Oracle offers a pretty good tutorial on this.

  • Documentation on variables and methods are described in the Java source files as Java comments in a special format
  • The utility javadoc reads Java source files and creates html pages with the appropriate documentation for a class.

The format for the documentation is a special case of the multiline Java comment. It looks like this:

/ ** * This is a documentation comment * Here is another line with a documentation comment * /

Java comments can be formatted with html.

Summary for a class

Begin the documentation of a class with a summary of its function.

For the class Ware.java it can look like this:

/ ** * Goods are used to manage goods with prices and names in a warehouse. * @author Stefan Schneider * @version 1.1 * @see Lager * / public class goods {...}

The class documentation allows the use of tags with which you can add further information. The following "tags" can be used for classes:

Documentation of class variables

To document attributes, the documentation precedes the declaration. With the class Would this can be done, for example, as follows:

public class Ware {... / ** * The current VAT rate 2010. * It is currently {@value}. * * @since 1.0 * / public static final double mws = 0.19; ...}

The following "tags" can be used for class variables:

Documentation of constructors and methods

The documentation of constructors and methods is also placed directly in front of the implementation of the corresponding method as a Java comment. In addition to the significance of the method, this can also be used to document the input and output parameters. See the following example:

/ ** * Returns the name of a product. * @return name of the goods * / public String get_name () {return name;} / ** * Set a new net price * @param npr the new net price * / public void set_nettoPreis (int npr) {...}

The following tags are possible for methods and constructors:

The JDK program javadoc (Oracle Documentation) generates Java API descriptions in html format from Java source files.

In its simplest form, you can generate Java API documentation with the following command:

$ javadoc JavaSourceFile.java ... JavaSourceFile1.java

The command javadoc has numerous options (see Oracle documentation) that can be inserted directly after the command. The most important are:

  • -author Generation of documentation taking into account the @author Day
  • -d directory Generates the documentation in the specified directory
  • -help shows the online help
  • -private generates documentation for private attributes too
  • -sourcepath sourcepathlist List of directories in which source files are searched for
  • -version Generation of documentation taking into account the @version Day

For a class Ware.java with all components:

/ ** * This is the documentation for the goods class. Goods are used to manage goods * with prices and names in a warehouse. * @author Stefan Schneider * @version 1.1 * @see Lager * / public class goods {/ ** * The current VAT rate 2010. * It is currently at {@value}. * * @since 1.0 * / public static final double mws = 0.19; private double net price; // declaration public boolean halbeMws; private string name; / ** * Constructor for the goods class * @param n the name of the goods * @param np the net price * @param hmws half the VAT rate for goods valid * / public goods (String n, double np, boolean hmws) {name = n ; net price = np; half mws = hmws; } / ** * Returns the name of a product. * @return name of the goods * / public String get_name () {return name; } / ** * Set a new net price * @param npr the new net price * @see "The small businessman. Business administration for retailers" * / public void set_nettoPreis (double npr) {nettoPreis = npr; } / ** * Print out all values ​​on the console * / print public void () {System.out.println ("Name:" + name); System.out.println ("net:" + net price); System.out.println ("gross:" + gross price ()); System.out.println ("Half VAT:" + half VAT); } / ** * Output of the net price * @return the net price * / public double nettoPreis () {return nettoPreis; } / ** * Output of the gross price * @return the gross price * / public double bruttoPreis () {double bp; // temporary variable; no class variable if (halbeMws) {bp = Math.round (net price * (mws / 2 + 1) * 100) / 100; } else {bp = Math.round (net price * (mws + 1) * 100) / 100; } return bp; }}

The documentation can be opened with the command javadoc to be generated. For the example shown above, two options for generating the author and the version are required. The options allow the information about authors and versions to be omitted if desired:

$ javadoc -author -version Ware.java

The command creates a series of html files in the same directory. The generated file index.html looks like this (screen shot):