How to document args in Java main

Question

How do you go about documenting the contents of the args parameter in:

public static void main(String[] args) {
    ...
}

I'm not asking about how to use the @param block tag in javadoc, but instead how to document what the contents of each item in the array should be.

For example: "args[1] is width, args[2] is height, etc".

Is <ol><li></li></ol> the way to go?

Answer 1

You can only do that in an informal way, by writing down some text within your javadoc that describes the expected arguments.

Meaning: there is no single, correct approach here.

In other words: you should use that option, that works best for you, and the other people in your team/project.

If your "team styleguide" allows (asks?) you to use HTML tags within javadoc, then use HTML tags. If your team has some more sophisticated approach that allows for some kind of markdown language, then use that. Otherwise, you probably should only be using {@code} to highlight certain parts.

Long story short: there is no exact rule here; so you should to what best fits your needs.

But keep in mind: maybe the javadoc is not so important in the end. If you think your application is used from the command line directly, than your main focus should be that something like "java -jar yourjar --help" gives reasonable output. And that you do not re-invent the wheel in terms of "argument" parsing. In other words: there are quite some libraries out there that you can use for command-line-parsing. And I am pretty sure that they should have support for documenting the potential arguments for command line users.

What I am saying is: in a "normal" setup, I would expect that those people interested in invoking your main method will not be reading javadoc. They want to look at some help screen to understand which options they can use!