开发者

What should I write in my javadoc class and method comments?

I currently have created an application and need some help with writing my javadoc for it.

Here is the code:

import java.lang.*;
import java.util.*;
import java.io.*;
import java.net.*;

/**
*@author Name HERE 
*@version 1.0
* The Assignment2App public class represents a menu application that will form
* the base of the other source files which will be able to run within this program.
* Users will be able to run another source file within this pogram of which they choose
* by selecting a number specified by the output presented to them on the command window.
*/
public class Assignment2App extends Object
{

/**
*
*
*
*
*/
    public static void main(String[] argStrings) throws Exception
    {
        //Giving the boolean variable called 'exitApp' a value of 'false'
        boolean exitApp = false;

        //Enabling the scanner to read keyboard input
        Scanner keyboard = new Scanner(System.in);

        //Start of the do loop
        do
        {
            //Print out to the command window the name of the program including blank lines to make the program easier to read
            System.out.println("");
            System.out.println("");
            System.out.println("*************************************************************");
            System.out.println("NAME - Programming Assignment 2 - Programming Portfolio");
            System.out.println("*************************************************************");
            System.out.println("");
            System.out.println("");

            System.out.println("0 - Exit");
            System.out.println("1 - Execute Enhanced For Loop");
            System.out.println("2 - Execute For Loop");
            System.out.println("3 - Execute Do While Loop");
            System.out.println("4 - Execute If Statement");
            System.out.println("5 - Execute Switch Statement");
            System.out.println("");

            //Sends output to the command window asking the user to choose an application to execute
            System.out.print("Please choose an application to execute or press 0 to exit > ");

            //Stores the user input into an integer variable called 'choice'
            int choice = keyboard.nextInt();

                //Start of the switch statement, taking the users input 'choice' to select a case
                switch (choice)
                {
                    //This case closes the application by changing the value of the variable called 'exitApp to 'true'
                    case 0:
                开发者_运维技巧    exitApp = true;
                    break;

                    //This case executes the 'EnhancedForLoop.java' main method
                    case 1:
                    EnhancedForLoop.main(null);
                    break;

                    //This case executes the 'ForLoop.java' main method
                    case 2:
                    ForLoop.main(null);
                    break;

                    //This case executes the 'DoWhileLoop.java' main method
                    case 3:
                    DoWhileLoop.main(null);
                    break;

                    //This case executes the 'IfStatement.java' main method
                    case 4:
                    IfStatement.main(null);
                    break;

                    //This case executes the 'SwitchStatement.java' main method
                    case 5:
                    SwitchStatement.main(null);
                    break;

                    //This case is executed if the user enters an incorrect number, the user is then presented with 'Please select a number!'
                    default:
                    System.out.println("Please select a number!");
                    break;
                }
          //Part of the do-while loop, this ends the application once the variable called 'exitApp' is changed to 'true'
        } while (exitApp == false);

    }
}

I have no idea what sort of things to write for a 'method' and for a 'class'. I have already had a go at the class Java documentation using javadoc, but can anyone confirm if it's correct?


Check How to Write Doc Comments for the Javadoc Tool

All the options are well explained. A commented class example is included.

Method descriptions begin with a verb phrase. A method implements an operation, so it usually starts with a verb phrase: Gets the label of this button. (preferred) This method gets the label of this button. (avoid)

Class/interface/field descriptions can omit the subject and simply state the object. These API often describe things rather than actions or behaviors: A button label. (preferred) This field is a button label. (avoid)


For a method:

 /**
 * Validates a chess move. Use {@link #doMove(int, int, int, int)} to move a piece.
 * 
 * @param theFromFile file from which a piece is being moved
 * @param theFromRank rank from which a piece is being moved
 * @param theToFile   file to which a piece is being moved
 * @param theToRank   rank to which a piece is being moved
 * @return            true if the chess move is valid, otherwise false
 */
boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank)
{
    ... 
}

For a Class

/**
 * Description
 * @author Gazler.
 * @version 2.0,    
 * @since SDK1.4
 */


The class doc looks decent. As you use a class, it never hurts to brush up the javadoc if it was unclear.

For the method, what does the method do? In this case, the method is the only thing in the class, so you can probably have very light documentation on the method itself.


In real-life applications, you want to tell the other programmers what your class' and methods' contracts are. What does a method require of its caller? What does it guarantee about its result? Is it thread-safe? Avoid this style of documentation:

/**
 * Set the person's age.
 * @param age The age to give this Person.
 */
public void setAge(final int age) {
    this.age = age;
}

The documentation is all noise; all it says is that setAge sets the age, and anyone can guess that.

Instead, write this as:

/**
 * Set the person's age.
 * @param age The age to give this Person. {@code age} must be nonnegative.
 * @throws IllegalArgumentException if {@code age < 0}.
 */
public void setAge(final int age) {
    if (age < 0) {
        throw new IllegalArgumentException(
            "Attempt to set a Person's age to a negative value: " + age);
    this.age = age;
}

It's also possible to use JSR 303 annotations to document constraints, and even to enforce them. The signature would be:

public void setAge(final @Min(0) int age);
0

上一篇:

下一篇:

精彩评论

暂无评论...
验证码 换一张
取 消

最新问答

问答排行榜