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“:
Change the default comment to something like this. Important: Use only one sentence and don’t forget the point at the end.
This will result in:
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:
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:
and:
