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?

• Dylan Meeus: This is probably what you are looking for: stackoverflow.com/questions/2273170/…
• benscabbia: @DylanMeeus excellent exactly what I was looking for. Therefore my javadoc example is correct
• gnat: "The Javadoc tool can generate output originating from four different types of "source" files: Source code files for Java classes (.java) - these contain class, interface, field, constructor and method comments..." (SO tag wiki -> How to Write Doc Comments for the Javadoc Tool)
• user22815: You can have the brevity of example 2 and the benefits of example 1 by using a single-line JavaDoc: /** Keeps track of all usernames in the system. */
• benscabbia: @Snowman I was unaware of that, thanks for the info!

Answer 1

Private fields are usually ignored by documentation tools, so when you ship your API to a third party, they 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 IDEs 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.

• benscabbia: thanks for the answer. My gut feeling was to use JavaDoc but I was unsure due to Private fields are usually ignored by documentation tools. (I will accept ASAP)
• Andrew T Finnell: None of those reasons are pragmatic nor useful reasons to do something. Doing something just because other places do it that way is a very poor reason to do it. Documentation just to meet guidelines that provides no value seems like a waste. Places seem to go overboard with javadoc's or never do it. The happy medium is the best.