Documenting command line arguments

Question

I'm very new to javadoc, and I'm trying to put together a set of guidelines for our developers to follow. One thing I came accross was command line arguments. If a main function is expecting command line arguments, how would this be documented, should @param be used? I didn't see anything about this in the guidelines sun has posted. Any help is greatly appreciated.

Answer 1

This is my own personal opinion, so don't treat it as a "fact", but I don't think Javadoc is best suited for specifying command line arguments. You could do the following:
*  Description of main() here...
* @param args First parameter = xxx, Second parameter = yyy;
public static void main(String[] args)
}In this way you can specify all command-line parameters that are required in order to make the appliction run.
BUT...
Javadoc is meant more to be a programmatic guide to how to allow Java classes to interoperate. Java classes (mostly) will not care at all what the command-line parameters to the main invocation are. That is information that is only really needed to be known by the application executor at runtime.
Therefore, for all my apps, I do the following to comment what types of parameters should be passed to the invocation of the application:
* My App comments...
* @param args Run application without any parameters to see list of all necessary command-line parameters.
public static void main(String[] args)
   if (args.length < 1)
      System.out.println("This application allows the following parameters:");
      System.out.println("   Param#1 = xxx, <description>");
      System.out.println("   Param#2 = yyy, <description>");
      System.exit(0);
}In this way, you do not clutter up the Javadoc APIs (used for classwise interaction) with command-line parameters, but the command-line parameters are still specified by "documentation" (running the application without any parameters).
If parameters are optional, instead of mandatory, you could do something similar...
* Documentation...
* @param args Run -h as first flag for list of all optional parameters.
public static void main(String[] args)
   if ((args.length > 0) && (args[0].equals("-h"))
      // Print out all possible parameters.
}Anyway, this system has held me in good stead for the last couple of years.