我應該在我的javadoc類和方法注釋中寫什么？

Question

我目前已經創建了一個應用程序，需要一些幫助來編寫我的javadoc。

這是代碼：

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);

    }
}

我不知道為'方法'和'類'寫什么樣的東西。 我已經使用javadoc了解了Java類文檔，但任何人都可以確認它是否正確？

Answer 1

檢查如何為Javadoc工具編寫Doc注釋

所有選項都有很好的解釋。 包含一個注釋類示例 。

方法描述以動詞短語開頭。 方法實現了一個操作，因此它通常以動詞短語開頭：獲取此按鈕的標簽。 （首選）此方法獲取此按鈕的標簽。 （避免）

類 /接口/字段描述可以省略主題並簡單地說明對象。 這些API通常描述的是事物而不是行為或行為：按鈕標簽。 （首選）此字段是按鈕標簽。 （避免）

Answer 2

對於一種方法：

 /**
 * 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)
{
    ... 
}

對於一個班級

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

Answer 3

班級文檔看起來不錯。 當你使用一個類時，如果不清楚那么刷javadoc永遠不會傷害。

對於該方法，該方法有何作用？ 在這種情況下，該方法是該類中唯一的方法，因此您可以擁有關於方法本身的非常簡單的文檔。

Answer 4

在實際應用程序中，您希望告訴其他程序員您的類和方法的合同是什么。 方法對其調用者有什么要求？ 它對結果有什么保證？ 它是線程安全的嗎？ 避免使用這種文檔：

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

文件全是噪音; 它說的是setAge設定的age ，任何人都可以猜到。

相反，寫這個：

/**
 * 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;
}

也可以使用JSR 303注釋來記錄約束，甚至強制執行它們。 簽名將是：

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