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.
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.
Javadoc comments and usage statements normally serve
entirely different audiences -- Javadoc comments
are for developers and usage statements are for users.
If you want developers to see these comments, you
could certainly do something like the following.
The second argument to @param can be any free-form
text.
/*
* My App comments...
*
* @param args
*This application allows the following parameters:
*<ul>
*<li> xxx - <description of xxx>
*<li> yyy - <description of yyy>
*</ul>
*Run application without any parameters to see list of all necessary command-line parameters.
*/
Of course, this isn't as nice as having tags dedicated
to those parameters. You could write to do
something more sophisticated which would move the
<ul> and <li> tags into the taglet. If you'd like
such a taglet, I could write one for you.
-Doug Kramer
Javadoc team
I think you could also make a custom in-line formatting for the param test.
Until then, I do usually just put it into the body unformatted. Since it is for programmers, I think that indicies usually suffice.
i.e.
/**
* The method.
@param argArray [0] value 1 description, [1] value 2 description, ...
*/
or if you used an ordered list, starting at 0.
/**
* The method.
@param argArray
* <OL START=0 TYPE="1">
*<LI>value 1 description</LI>
*<LI>value 2 description</LI>
...
* </OL>
*/
