Menu
I'm documenting some code, and I have a private HashMap. I'd like to specify information about what is expected from the key and value. Right now I have:
/**
* HashMap where key=word, value=part of speech
*/
private HashMap<String, String> dictionary;
However, this seems hard to read, and also like it won't work well when I have something more complex like
HashMap<String, HashMap<String, String>>
What are best/common practices for documenting maps?
858
From the main menu, select Tools | Generate JavaDoc. In the dialog that opens, select a scope — a set of files or directories for which you want to generate the reference, and set the output directory where the generated documentation will be placed.
The HTML format is used for adding the convenience of being able to hyperlink related documents together. The "doc comments" format used by Javadoc is the de facto industry standard for documenting Java classes. Some IDEs, like IntelliJ IDEA, NetBeans and Eclipse, automatically generate Javadoc HTML.
The correct approach is an @param tag with the parameter name of <T> where T is the type parameter name. There should be one blank line between the Javadoc text and the first @param or @return. This aids readability in source code. The @param and @return should be treated as phrases rather than complete sentences.
Before using JavaDoc tool, you must include JavaDoc comments /**……………….. */ providing information about classes, methods, and constructors, etc. For creating a good and understandable document API for any java file you must write better comments for every class, method, constructor.
If you need a small javadoc, I suggest the following:
/**
* Dictionary is a {@link Map} collection that contains {@link Object1} as
* key and {@link Object2} as value.
*/
private Map<Object1, Object2> dictionary = new HashMap<>();
@link keywork will redirect you on instance definition.
Note : Using an interface as a type (Map instead of HashMap) should be preferred.
184
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
