Generating documentation

Javadoc in Eclipse

You can generate the documentation for the Point class in Eclipse in the following manner.

1. Open Eclipse project folder (Geometry in our case).

2. In the menu bar, select Project → Generate Javadoc.

3. At first step of the wizard, you can define settings for:

3.1. Select path for the javadoc.exe tool from the JDK.

3.2. Project resources for which to generate Javadoc.

3.3. Classes and methods for which to generate Javadoc based on their visibility.

3.4. Location of the Javadoc (by default it will be placed in the doc folder in the project location).

4. In the next step provide the documentation title.

5. In the last step, select the checkbox 'Open generated index file in browser'.

Note: There are several features in the wizard which you can explore at your leisure.

Utility of Javadoc

You don't have to write a separate manual stating what functionalities are supported by your class. It is automatically created by javadoc. The user of your code gets enough information to know the classes you have implemented and methods supported along with the argument and return types. By publishing your compiled .class files (byte code) and the java documentation, any programmer can use your code without having to know the underlying implementation.

Javadoc at command-line

CMD> javadoc -d docs Point.java // Generates many files including Point.html in docs folder

Open Point.html in a browser. It contains the necessary information for an user to know what all functionalities are supported by Point so that they can use it.

Take your time to understand what is in the html page.

Are private attributes or methods mentioned in the html? Now change an attribute to public.

public int x;

Run javadoc, regenerate Point.html and check.

Now in Point.java, just above the add method include a comment using /** ... */

  /** This method adds two Points and returns the sum */ 
  public Point add(Point q) {
       // Your code
  }

Run javadoc, regenerate Point.html and check. Adding comments help!!

javadoc has great many features. For more check out the web.

Object Oriented Programming