Что я должен написать в комментариях к классу и методу 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);

    }
}

Я понятия не имею, что написать для «метода» и «класса». Я уже изучил документацию по классу Java с использованием javadoc, но кто-нибудь может подтвердить, правильно ли это?

Answer 1

Проверка Как написать комментарии к документу для инструмента Javadoc

Все варианты хорошо объяснены. пример класса с комментариями включен.

Метод описания начинаются с глагольной фразы. Метод реализует операция, поэтому она обычно начинается с фразовый глагол: Получает метку этой кнопки. (Предпочтительный) Этот метод получает метку этой кнопки. (Избежать)

Класс / описания интерфейса / поля могут опускать тему и просто указывать предмет. Эти 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

В реальных приложениях вы хотите сообщить другим программистам, каковы ваши классовые и методические контракты. Что метод требует от своего вызывающего? Что это гарантирует о своем результате? Это потокобезопасно? Избегайте этого стиля документации:

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

Answer 4

Классный документ выглядит прилично. При использовании класса никогда не повредит очистить Javadoc, если это будет неясно.

Для метода, что делает метод? В этом случае метод является единственным в классе, поэтому вы можете иметь очень легкую документацию по самому методу.