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

Question

I have currently created an application and I need help 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 things to write for the "method" and for the "class". I already dealt with Java class documentation using javadoc, but can anyone confirm if this is fixed?

Answer 1

Tick How to write Doc comments for the Javadoc tool

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

. :        . ()        . ( )

// . 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

doc . , javadoc, .

, ? , .

Answer 4

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

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

The documentation contains all the noise; all this speaks of what setAgesets age, and anyone can guess that.

Instead, write this as:

/**
 * Set the person 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 age to a negative value: " + age);
    this.age = age;
}

It is also possible to use JSR 303 annotations to document constraints and even enforce them. The signature will be as follows:

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