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

检查How to Write Doc Comments for the Javadoc Tool

所有选项都有很好的解释。包含commented class example。

方法说明以动词短语开头。一种方法实现了   操作，所以通常以a开头   动词词组：         获取此按钮的标签。（优选的）         此方法获取此按钮的标签。（避免）

类 / interface / field说明可以省略主题并简单说明   物体。这些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,  &nbsp; 
 * @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);

我应该在我的javadoc类和方法注释中写什么？

4 个答案: