Need some help with Javadoc....

Question

Hello, I currently have create an application and need some help with 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 sort of things to write for a 'method' and for a 'class'. I have already had a go at the class java documentation using javadoc but can anyone confirm if it's correct.

Thanks very much,

Chris.

Answer 1

Check How to Write Doc Comments for the Javadoc Tool

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

Method descriptions begin with a verb phrase. A method implements an operation, so it usually starts with a verb phrase: Gets the label of this button. (preferred) This method gets the label of this button. (avoid)

Class/interface/field descriptions can omit the subject and simply state the object. These API often describe things rather than actions or behaviors: A button label. (preferred) This field is a button label. (avoid)

Answer 2

The class doc looks decent. As you use a class, it never hurts to brush up the javadoc if it was unclear.

For the method, what does the method do? In this case, the method is the only thing in the class, so you can probably have very light documentation on the method itself.