Java Doc - Do fields also get documented?

Question

This is a really simple question but oddly, I'm finding it difficult to get a definite answer....

What do you do with fields? Is this valid?

/** 
 * Keeps track of all usernames in the system.
 */   
private List<String> usernames = new ArrayList<>();

Or is above ingnored by documentation tools, so would it be best to do something like:

 //Keeps track of all usernames in the system.   
private List<String> usernames = new ArrayList<>();

Since (from what I see), documentation only shows methods, constructors and classes, what do programmers usually do with fields?

Answer 1

Private fields are usually ignored by documentation tools, so when you ship your API to a third party, he/she will not be able to see any documentation regarding private fields (unless you specify that you also want to include private fields in the documentation during the documentation generation phase of your project).

That being said, I think it is a good idea to use JavaDoc to also document private fields because:

• It will conform to the rest of the other documentation.
• Most IDE's will extract JavaDoc and show it to you when you try and access different object properties. This can save time going around the code to see what is the purpose of a particular variable.
• In the event that you will want to include private field documentation into your documentation, all the work will have already been done.