User Tools

Site Tools


javadoc_documentation_style

JavaDoc Documentation Style

Documentation is an important element in ensuring code is understandable. JavaDoc creates documents in HTML format from code and requires a specific style of documentation to function properly.

The full JavaDoc reference can be found at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html


JavaDoc comments are embedded in /** .... */ tags. The @ symbol is used prior to using definitions such as parameters, returns, author, version, etc. A * is used at the beginning of every line of documentation inside the tags.

The beginning of code should include a description of the class file followed by the name of the author, the version of the code and/or the date of last revision.

Before every method a short, single, line of code should be used to describe the method followed by, if desired, a longer more descriptive set of paragraphs. Then a listing of the major parameters (@param) and what the method returns (@return) if applicable.

Say the below code is used:

import java.util.Scanner;
 
public class HelloWorld {
 
     public static void main(String[] args) {
 
          Scanner keyboard = new Scanner(System.in);
 
          String input;
 
          System.out.println("What is your name?");
 
          input = keyboard.nextLine();
 
          hello(input);
 
     }
 
     public static void hello(String name) {
 
          System.out.println("Hello World! Please welcome " + name + " to the world of Computer Science!");          
 
     }
}

Proper JavaDoc documentation style would look like the following:

import java.util.Scanner;
 
/**
 * The HelloWorld class is used to demonstrate how to use the scanner utility 
 * and print a message to the terminal using input from the scanner.
 * <br><br>
 * @author CSci Wiki
 * @since 7/25/13
 */
 
public class HelloWorld {
 
     /**
      * main accepts user input for future display.
      * <br><br>
      * main prompts the user to enter their name.
      * Once a name has been entered the hello method is called for output.
      * <br><br>This method requires java.util.Scanner
      * <br>  keyboard: An instance of Scanner
      * <br>  input: A string for storing the user's name
      * @param args is required for main methods, but not used by this method
      */  
 
     public static void main(String[] args) {
 
          Scanner keyboard = new Scanner(System.in);
 
          String input;
 
          System.out.println("What is your name?");
 
          input = keyboard.nextLine();
 
          hello(input);
 
     }
 
     /**
      * hello outputs the string input from the Scanner in the main method.
      * <br><br>
      * hello uses the input string from the Scanner to display a sentence as output.
      * <br><br> 
      * @param name is the input string from the Scanner in the main method
      */
 
     public static void hello(String name) {
 
          System.out.println("Hello World! Please welcome " + name + " to the world of Computer Science!");          
 
     }
}
javadoc_documentation_style.txt · Last modified: 2015/07/28 15:05 by skerlin