我应该在我的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
 */