Jul 052014
 

Javadoc for java Packages

It is also possible to add a comment / short description of a package. This can be done using a file called package-info.jave inside the package. When using eclipse, you can check the option „Create package-info.java“:

Create package-info.java

Create package-info.java

Change the default comment to something like this. Important: Use only one sentence and don’t forget the point at the end.

Change comment to something like this

Change comment to something like this

This will result in:

Package description

Package description

 

Using Javadoc for classes

To describe classes, you should start with a single sentence at the beginning. This sentence is used on the overview page of a package where all classes are listed (with a short description which is this sentence). Dont forget the point at the end.

The next paragraph contains a more detailed description that will be shown on the detail page of the class. Here you can use some html tags. In this case I used a list. After that you can add some javadoc parameter.

package com.pbo.Game;

/**
 * This Class represents the main class of the F1 Betting Game.
 * <p>
 * This Class handles all the database connection stuff, it creates the GUI
 * and it contains all the rules. See method: displayRules.
 * <br>
 * It also Starts the database connection, create instances of users and rankings and so on.
 * <ul>
 * 		<li>You can also</li>
 * 		<li>use a list</li>
 * 		<li>here in the description of the class</li>
 * </ul>
 * 
 * @author philipp
 * @version 0.1
 */
public class GameStarter {
    // your class here
}

Result of that comment:

Package Overview shows all classes with a short description

Package Overview shows all classes with a short description

 

Overview of one class

Overview of one class

 

Javadoc for methods

To describe methods you should begin with a short description in a single sentence. This sentence will be displayed in the method-overview of the class. After that sentence you should describe your method more detailed. This will be the description of the method. There you can use html-tags like linebreak <br> , lists <ul> , <li>, and more. You can create paragraphs by using the <p> tag. See the example below:

/**
 * This method displays all the rules for the game.
 * <p>
 * Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
 * eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
 * voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet
 * clita kasd. <br>
 * Nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
 * sed diam voluptua.
 * <p>
 * Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
 * eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
 * voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet
 * clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit.
 * <p>
 * Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
 * eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
 * voluptua dolor sit amet.
 * <ul>
 * <li>Rule 1 ...</li>
 * <li>Rule 2 ...</li>
 * <li>Rule 3 ...</li>
 * </ul>
 * 
 * @param userName
 *            The username of the Player
 * 
 * @param difficulty
 *            The difficulty of the game, from 1 to 10, where 1 is simple
 *            and 10 means strong
 * @return the status code after the game has finished. 1=won, 2=lost
 */
public int displayRules(String userName, int difficulty) {
	// your code goes here
	return 2;
}

Results in:

Javadoc Method Overview

Javadoc Method Overview

and:

Javadoc Method Details

Javadoc Method Details

 

Sorry, the comment form is closed at this time.