Do I need to javadoc every single method or just the 'main' method in java?

Question

Java example method:

//Stores the user input into an integer variable called 'choice'
int choice = keyboard.nextInt();

Do I need to write javadoc for a simple method like this or should I only document the main method of any program, if so then what sort of things should I write for the main method?

Thanks,

Chris.

Answer 1

Need? That depends on what you mean by "need".

I think there's a few confusions in your question. One of them is what constitutes a method. You seem to be asking about comments in general. Javadocs are a specific form of comment (with a particular syntax). Also, a quibble: your example above isn't a method. It's a single line of code.

But addressing just that, I wouldn't use that comment. Clearly you're setting a variable called "choice". The only thing interesting there is what nextInt does, but anyone curious should be able to hover over the nextInt() method and see its javadocs.

Answer 2

This was explained in your other thread: http://stackoverflow.com/questions/1834621/need-some-help-with-javadoc/1834645#1834645

What you have posted is not a method either. You do not need to comment every line of code, even for an assignment. If you have something obvious such as:

i++;

You do not need to comment it with "increments i by one."

Again, code comments (including JavaDoc) do not affect the execution of the code.

Answer 3

First off, that example is not javadoc, just a code comment

Here is a tutorial on javadoc How to write javadoc

And you should only javadoc public facing methods