Java Doc comments

[kevin Abel]

I am new to creating Java documentation from Eclipse.  
After adding the /**  and */ , some text and @ tags such as @param and @return I
Select Project/Generate Javadoc.  
I noticed error messages flying by.  
This example is from my maruch book.  The ones from the book seem to work.  
The ones in the book look like:

@param code A <code>String</code> for the product code.

I don't know what the code A means after param

The function that it is commenting looks like:

public void setCode(String code) {
  this.code = code;
}

I don't know why I am getting errors that I show below.

Thanks,

Kevin

package murach.business;

import java.text.NumberFormat;

/**
 * The <code>Product</code> class defines a product and is used
 * by the <code>LineItem</code> and <code>ProductDB</code> classes.
 * @author KAA
 * @version 8.0
 */
public class Product  {

    private String code;
    private String description;
    private double price;

    /**
     * Creates a <code>Product</code> with default values.
     * By the way...this is a constructor
     * @param <Code> void return type
     * @return A <code>String</code> nothing is returned from this method KAA
     */
    public Product() {
        code = "";
        description = "";
        price = 0;
        
    }

    /**
     * Sets the product code.
     * @param <code> String code KAA </code>
     * @return void
     */
    public void setCode(String code) {
        this.code = code;
    }

    /**
     * Gets the product code.
     * @param <code> no value in </code>
     * @return no value out KAA
     */
    public String getCode() {
        return code;
    }

    /**
     * Sets the product description.
     */
    public void setDescription(String description) {
        this.description = description;
    }

    /**
     * Gets the product description.
     */
    public String getDescription() {
        return description;
    }

    /**
     * Sets the product price.
     */
    public void setPrice(double price) {
        this.price = price;
    }

    /**
     * Gets the product price.
     */
    public double getPrice() {
        return price;
    }

    /**
     * Gets the product price with currency formatting.
     */
    public String getPriceFormatted() {
        NumberFormat currency = NumberFormat.getCurrencyInstance();
        return currency.format(price);
    }

    /**
     * Gets the default string for the product.
     */
    @Override
    public String toString() {
        return description;
    }
}

Error messages below:

Building tree for all the packages and classes...
Generating C:\murach\java_eclipse\ch13_ex3_LineItem\doc\murach\business\Product.html...
C:\murach\java_eclipse\ch13_ex3_LineItem\src\murach\business\Product.java:32: error: @param name not found
    * @param <code> String code KAA </code>
              ^
C:\murach\java_eclipse\ch13_ex3_LineItem\src\murach\business\Product.java:32: error: unexpected end tag: </code>
    * @param <code> String code KAA </code>
                                    ^
C:\murach\java_eclipse\ch13_ex3_LineItem\src\murach\business\Product.java:33: error: invalid use of @return
    * @return void
      ^
C:\murach\java_eclipse\ch13_ex3_LineItem\src\murach\business\Product.java:35: warning: no @param for code
   public void setCode(String code) {
               ^
C:\murach\java_eclipse\ch13_ex3_LineItem\src\murach\business\Product.java:41: error: @param name not found
    * @param <code> no value in </code>
              ^
C:\murach\java_eclipse\ch13_ex3_LineItem\src\murach\business\Product.java:41: error: unexpected end tag: </code>
    * @param <code> no value in </code>
                                ^
C:\murach\java_eclipse\ch13_ex3_LineItem\src\murach\business\Product.java:51: warning: no @param for description
   public void setDescription(String description) {
               ^
C:\murach\java_eclipse\ch13_ex3_LineItem\src\murach\business\Product.java:58: warning: no @return
   public String getDescription() {
                 ^
C:\murach\java_eclipse\ch13_ex3_LineItem\src\murach\business\Product.java:65: warning: no @param for price
   public void setPrice(double price) {
               ^
C:\murach\java_eclipse\ch13_ex3_LineItem\src\murach\business\Product.java:72: warning: no @return
   public double getPrice() {
                 ^
C:\murach\java_eclipse\ch13_ex3_LineItem\src\murach\business\Product.java:79: warning: no @return
   public String getPriceFormatted() {
                 ^
C:\murach\java_eclipse\ch13_ex3_LineItem\src\murach\business\Product.java:20: error: @param name not found
    * @param <Code> void return type
              ^
C:\murach\java_eclipse\ch13_ex3_LineItem\src\murach\business\Product.java:21: error: invalid use of @return
    * @return A <code>String</code> nothing is returned from this method KAA

[Junilu Lacar]

Don't put <code> tags around the parameter name of @param, and don't put the parameter type either. That's already obvious in the method signature. Don't put an @return for a void method. For example, your setCode() method should be JavaDoc'd like this:
/** * Sets the product code to the specified value. * * @param code the code for this product */ public void setCode(String code) {   ...
The JavaDoc tool will take care of assigning a uniform style to certain elements.

[kevin Abel]

Junilu,
I appreciate the response.

Your answer gave me enough information to move ahead.  Now I am getting errors when generating the documents.  

It says that @param s are missing.   @returns are missing.  
Is there logic that if I start using tags that I have to use them everyplace?

In your example for SetCode where is says:
* @param code the code for theis product
Is the word after @param indicating the next word is the parameter that it is making a comment for?  

I get error messages for methods that return void.  If I don't include it then I get error messages. My book is showing this for voids:
* @return A <code>String</code> for the product code.  I don't know what the A is for.  You are saying not to use add parameter types.  How do I do this for voids?

[Campbell Ritchie]

kevin Abel wrote:. . . Is there logic that if I start using tags that I have to use them everyplace?

Yes, you should use the appropriate tags everywhere. An IDE will make wrriting documentation comments easier because it will fill in part of the @xzy tags automatically.

. . . Is the word after @param indicating the next word is the parameter that it is making a comment for?

Yes.

. . . . My book is showing this for voids:

Which book? Murach?
Don't write @return tags for a void method.

. . . You are saying not to use add parameter types. . . .

Parameters are not return types. Junilu said to omit the type for parameters, because the type is written elsewhere. Similarly, if there is a return type, you describe what is returned but don't need to give it a type. Remember that return values don't have names.

Have a look here for more advice about the documentation comments. There is also a section in Effective Java by Joshua Bloch, 2/e p203, 3/e p254.

[Mike Simmons]

Note that I'm using IntelliJ, and I don't feel like switching to Eclipse to verify if the behavior is the same.  So, I may be seeing different results than you, but I don't think so.  I believe both IDEs are simply forwarding messages from the javadoc tool, which is part of the JDK.

kevin Abel wrote:It says that @param s are missing.   @returns are missing.  
Is there logic that if I start using tags that I have to use them everyplace?

Not exactly.  First, I think you will see the same messages even if you use no tags.  If you generate javadoc at all, you will get those messages.  They don't occur on private methods though, only on the ones that are exposed

Also, note that they are warnings, not errors.  It's possible for you to ignore them, and you still get javadoc generated for all the tags you've set up correctly.  Personally, I think this is important - in many cases, it's possible to choose method names and parameter names such that the use of a method is obvious, and your javadoc comment won't add anything.  My rule of thumb is, don't make a javadoc comment unless you have something to add that isn't already obvious from the method signature (and return type, parameter names, throws clause, etc).  Don't even repeat that info in your comment... unless you're going to add something.  If there's nothing to add because you already chose really clear names, or already documented a concept somewhere nearby, don't feel guilty, just skip the comment, or the tag.  Life is too short to spend it generating redundant javadoc comments.  Or reading them.

kevin Abel wrote:I get error messages for methods that return void.  If I don't include it then I get error messages.

That seems very unlikely.  Can you show an example?  As Campbell says, you shouldn't have @return for a void method at all.

kevin Abel wrote:My book is showing this for voids:
* @return A <code>String</code> for the product code.  I don't know what the A is for.

The A is just the english word A.  This line gets rendered as "A String for the product code" - except the code tag makes it appear in a different font.

kevin Abel wrote:You are saying not to use add parameter types.  How do I do this for voids?

Well, there are a couple different things going on here.  On a parameter type, the one word immediately after the @param should exactly match the name of one of your method parameters.  That's how the javadoc tool knows which parameter your comment applies to.  So if you put < code >  here, you confuse the javadoc tool, and it doesn't know where to put your comment.  The rest of your param comment will probably not appear in the generated javadoc, because the tool doesn't know where to put it.

In a param tag, everything after the first word is basically just text plus html, so you can write anything you want, as far as the tool is concerned.  But we advise not repeating things like the type, because it's already obvious and redundant.   But that's a style choice.  Similarly, for a @return tag, there's no parameter name, and therefore no special rule about the first word after @return.  It's all just text and html, as far as the tool is concerned.  If a method is not void, then you can write @return followed by anything you want.  As a matter of style though, don't bother repeating things that are already obvious, such  as the return type.

[Campbell Ritchie]

Mike Simmons wrote:. . . This line gets rendered as "A String for the product code" - except the code tag makes it appear in a different font.

Like this:-
A String for the product code

. . . . don't bother repeating things that are already obvious, such  as the return type.

Which the book manages to disagree with.

If you go into the settings on Eclipse and use the code generation feature for setXXX() and getXXX() methods, it will generate this sort of code by default:-

private int flongler;
// ...
/**
 * Sets the flongler
 *@param the flongler to set
 */
private void setFlonger(int flonger) {
   this.flongler = flongler;
}

/**
 * Gets the flongler
 *@return the flongler
 */
private int getFlonger() {
   return flongler;
}

At least the enforces the discipline that each method has a documentation comment; maybe beginners should learn that first. Then they should learn to make such comments informative, and then omit them if they add nothing but clutter. In that case, explain what flongler means, or is it simply a word I made up for writing in this post? Let's look at a recent example. I changed Liutauras's suggestion to shorten the parameter name and moved the bit about being measured in km into the documentation comments. Somebody might think it is redundant to say anything about km, but I think it is necessary. Even if you live somewhere where they have never heard of miles, it is possible that taxis need a different measurement. If you charge so much per 250 metres, you would need to take the parameter in ¼km metres.
No, ¼km would be a disastrous unit to use. You would need to mention the units somewhere, and the documentation comments would be a good place to do that. The whole idea of documentation comments is to make the method/class easier for users to use.
Back to the taxi example, where some of the fields have really bad names. Let's say you have a getKilometres() method. In that case, kilometres represents the total distance the car has ever travelled, as shown on its odometer, so you could use the documentation comments to hide the badly‑named field. You can also use documentation comments to hide implementation details. If you look here, you can sweeten things by making the fields all private and then you can give both versions of the getSugarPercentage() method the same documentation comment. You probably shouldn't describe how that percentage is calculated, because that can preclude later changes. Which brings me to another thought, that maybe lots of getXXX() and setXXX() methods with inane documentation comments denotes too slavish an adherence to the bean “p‍attern”.

[Knute Snortum]

Mike Simmons wrote:My rule of thumb is, don't make a javadoc comment unless you have something to add that isn't already obvious from the method signature (and return type, parameter names, throws clause, etc).  Don't even repeat that info in your comment... unless you're going to add something.  If there's nothing to add because you already chose really clear names, or already documented a concept somewhere nearby, don't feel guilty, just skip the comment, or the tag.  Life is too short to spend it generating redundant javadoc comments.  Or reading them.

I agree with Campbell that it's a good idea to document every public (and maybe protected) method, and I'll add another reason.  Eclipse and IntelliJ (and Netbeans?) have the ability to display Javadocs when you hover over a usage of a method.  That is, you're not looking at the source of the method at the time.  Also, it's not good to leave out a public method in the Javadocs because you may be looking at the HTML that the Javadoc tool produces.  You want all your public methods to show up there.

[Junilu Lacar]

Another tip on style, when appropriate (which is probably the majority of the time), the first word of the JavaDoc comment should be a verb in the 3rd person declarative form (not 2nd person imperative) to convey the sense of an action taken. For example,

// AVOID these

/**
 * Calculate the length of the hypotenuse given the lengths of the two other sides.
 ...
 */
...

/**
 * Set the product code.
 ...
 */

// PREFER these

/**
 * Calculates the length of this triangle's hypotenuse given the lengths of the two other sides.
 ...
 */

/**
 * Sets this product's code to the specified value.
 ...
 */

So prefer verb forms like "Calculates" and "Sets" over "Calculate" and "Set".

Also note that when documenting an instance method, refer to the current object using "this" as in "this Product" or "this Triangle" and to a method parameter as "the specified value" or "the given value".

This is a nuance that is easily overlooked but can be seen being used quite extensively in the standard library JavaDocs. Take a quick look at the String JavaDocs. For example, the first sentence of the charAt() method's JavaDocs is: "Returns the char value at the specified index." For the indexOf() method, this is the first sentence: "Returns the index within this string of the first occurrence of the specified substring."

It's important to capture the general behavior of the method in the first sentence of the method's JavaDoc comment. The first sentence is what's shown in the summary of methods table at the top of the class' JavaDocs. The JavaDoc tool determines what constitutes the "first sentence" by looking for the first period (.) so you should also make sure you punctuate properly. I'm not exactly sure how to escape a period character so the tool picks up on the first unescaped one or if you can do that at all. I suspect there is a way though.

EDIT: Here's what the tool documentation says (emphasis mine): "The first sentence of each documentation comment should be a summary sentence that contains a concise but complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first block tag. The javadoc command copies this first sentence to the member summary at the top of the HTML page."

[Junilu Lacar]

Here's another article you can pick up a lot of tips from, including how to format the first sentence if it includes a period. https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html

[Mike Simmons]

Knute Snortum wrote:I agree with Campbell that it's a good idea to document every public (and maybe protected) method, and I'll add another reason.  Eclipse and IntelliJ (and Netbeans?) have the ability to display Javadocs when you hover over a usage of a method.  That is, you're not looking at the source of the method at the time.  Also, it's not good to leave out a public method in the Javadocs because you may be looking at the HTML that the Javadoc tool produces.  You want all your public methods to show up there.

But your public methods will show up in javadoc (for all the use cases you give) even if you don't put a javadoc comment on them.  (As we can see from the majority of open-source library APIs.)  Basically it will show the method signature, plus return type, parameter names, declared exceptions, modifiers, and annotations.  A javadoc comment represents additional text that will be incorporated into a comment.  That's why I focus on adding something new there, not just repeating what we already should know.

So given

    private void setFlonger(int flonger) {
        this.flongler = flongler;
    }

The generated javadoc (assuming we use the --private option) is already "private void setFlonger(int flonger)".  So adding "Sets the flonger" tells us nothing new.  And if that's the entirety of the comment, then it would have been better to delete it, in my opinion.  But I absolutely do endorse building on that comment, if you're going to add something useful.  In particular, I as a potential user of this method would really like to know... WTF is a flonger, anyway?  What does it mean?  I like all of Campbell's discussion of this above... knowing the units is quite important, if it has units.  Also, is there a minimum or maximum possible value?  That's the sort of thing I want to see in a javadoc comment, if there is one.      

But then, assuming your setFlonger() method is well documented... do you really need that same info for the getFlonger() method as well?  Probably not.  For getters and setters, I recommend documenting one, but not the other.  Eliminating pointless redundancy.  I usually prefer documenting setters, since that's where I might need more info on things like IllegalArgumentException.  If I'm working somewhere that really requires javadoc everywhere even when pointless, I would just do something like this:

    /**
     * @see #setFlonger(int) 
     */
    private int getFlonger() {
        return flongler;
    }

To make it clear where to go for more info.

For me it's all an extension of DRY.  Not just to avoid visual clutter, but also because comments can lie.  And, I find that when people are encouraged to javadoc everything, that leads to a lot of vapid comments that don't say anything useful.  I would rather people put their energy into a few good comments about things that were not obvious, than a bunch of useless ones.

[Junilu Lacar]

Mike Simmons wrote:... when people are encouraged to javadoc everything, that leads to a lot of vapid comments that don't say anything useful.  I would rather people put their energy into a few good comments about things that were not obvious, than a bunch of useless ones.

Absolutely.

This:
   /**     * Creates a <code>Product</code> with default values.     * By the way...this is a constructor     * @param <Code> void return type     * @return A <code>String</code> nothing is returned from this method KAA     */
versus
   /**     * Creates a blank product with an empty code and description and a price of zero.     */

[Campbell Ritchie]

Mike Simmons wrote:. . . WTF is a flonger, anyway? . . .

It's a flongler, something you flongle with

    /**
     * @see #setFlonger(int) 
     */
    private int getFlonger() {
        return flongler;
    }

. . .

Good idea, as long as it doesn't make the documentation harder to navigate. I don't think this sort of comment really helpful

The standard documentation for String wrote:Unless otherwise noted, passing a null argument to a constructor or method in this class will cause a NullPointerException to be thrown.

You only know about that sort of comment when you already know about it, but it does help you to DRY up, so that is definitely an argument with two sides.

@see firstPostOfMineWhereFlonglerAppears.

[Dave Tolls]

Campbell Ritchie wrote:It's a flongler, something you flongle with

Any relation to a floggle-toggle?

[Campbell Ritchie]

It's much more like a toggle‑floggle.

[Tim Holloway]

Yes, those messages come from the JavaDoc compiler. It will whine if you incompletely document something. It's not fatal to the process, but the generated documents will be less useful if you don't account for things.

Note that the first sentence of a JavaDoc block is used as the 1-line short description in the generated docs.

Also note that JavaDoc is generating HTML and it will happily incorporate any HTML tags that you provide in the JavaDoc text into the displayed webpage. That includes boldface/italics and the like, ordered and unordered lists, tables, and even images. I've been known to include flowcharts generated by graphviz, for example. As I've said before, you can actually generate a very complete manual just from JavaDocs.

When writing JavaDocs, there are two critical things to attend to:

1. The JavaDocs should tell the user what the class in question is good for, what its methods and properties are good for, and how to use them. And note here that some IDEs will offer pop-up snippets from the JavaDocs as part of their code completion options.

2. The JavaDocs should tell what not how. If you must explain the inner workings, fine, but that's really more for regular comments. The JavaDocs are primarily for external users and ideally the class being documented will be a "black box" where the actual implementation details can be taken for granted - and even change without notice.

If you are not familiar with Knuth's concept of Literate Programming, I recommend it. That's basically how I design and document.

[Campbell Ritchie]

Tim Holloway wrote:. . . If you must explain the inner workings, fine . . .

Apart from the fact that such comments may constrain you to keep the same implementation for ever.

[Junilu Lacar]

Here's the guideline from that Oracle document I cited previously:

If you must document implementation-specific behavior, please document it in a separate paragraph with a lead-in phrase that makes it clear it is implementation-specific. If the implementation varies according to platform, then specify "On <platform>" at the start of the paragraph. In other cases that might vary with implementations on a platform you might use the lead-in phrase "Implementation-Specific:". Here is an example of an implementation-dependent part of the specification for java.lang.Runtime:
On Windows systems, the path search behavior of the loadLibrary method is identical to that of the Windows API's LoadLibrary procedure.

The use of "On Windows" at the beginning of the sentence makes it clear up front that this is an implementation note.

[Campbell Ritchie]

I hadn't noticed that bit, but it is similar to what I was thinking. If you write that, “the current implementation does......” that makes it much clearer; saying it might change in future implementations give you a lot more wriggle room.

[Tim Holloway]

I see two different "implementation details" here. One being platform implementation - Windows, MacOS, Linux - and the other being actual implementation: what algorithms are being used, what various internal properties do, and so forth.

Regardless, implementation details should preferably be done in ordinary comments, not in JavaDocs. Only usage details should be in JavaDocs. Remember, a user should ideally be able to employ the class as a "black box", therefore the implementation details should be immaterial and not brought out in public documentaion. And the maintainer is already looking at the source and can therefore see the non-JavaDoc comments as well as the code.

I do have a convention of my own that implementation details of particular note are flagged with a special comment format of their own, such as "//. Special comment" (note the dot after the slashes. That's a legacy of my pre-Java days when I had a "JavaDoc" utility of my own (written in Perl), and while I've never exploited it in Java, it's easy to grep-search and even bring out as special output by customizing JavaDoc itself.

[Junilu Lacar]

To Tim's point, there are a few examples of implementation specific notes in the standard library JavaDocs, which is why I think it's explicitly called out in the JavaDoc style guide. I'm too lazy to look right now but if I recall correctly, you'll find a few in the Java Collections API JavaDocs. These notes will usually have to do with the particular algorithm that was chosen for an implementation class. This can influence design choices related to performance concerns, for example, and is important to know, especially when there are a few alternative implementations to choose from.

In those cases, I've usually just used the lead in of <b>Implementation Note: blah blah blah</b> in my JavaDoc comments if none of the other suggestions quite work.

In the cases that Tim points out should be left out of the JavaDoc comments, I'll usually put a rather conspicuous "developer note" in the general area of the code to which the note applies. For example:

private void someNastyStuff(. . .) {

  /*======
   * DEVELOPER NOTE: We did this because at the time, there was no way
   * we could easily refactor the flimflam component and decouple it from
   * blah, blah, blah...
   * 
   * If you ever get a chance to fix this or make it better, please update 
   * or delete this note. Sorry for the inconvenience and thanks for your
   * attention.
   */

[Junilu Lacar]

I did find this 2015 article though: https://blog.codefx.org/java/new-javadoc-tags/ about undocumented @apiNote, @implSpec, and @implNote. I have not tried these.

One of the quotes from that article:

the implementer Mike Duigou wrote:There are no plans to attempt to popularize these particular tags outside of use by JDK documentation.

[Campbell Ritchie]

Junilu Lacar wrote:. . . a few examples of implementation specific notes . . . I'm too lazy to look right now . . .

I am also too lazy, but I remembered having seen that sort of comment about Collections#sort(), which has a link to another similar implementation comment.

[kevin Abel]

Junilu, Mike, Campbell, Dave, Tim, Knute and anyone else I missed.  I appreciate all of the answers and feedback. I can not absorb all of it at once and I'm not on a project where I will need this right away.  I read through it for 10 minutes but there is too much to inhale at one time. I know where this material is so I can get back to it.  
I appreciate all of the time and effort you each put into this.  

[Campbell Ritchie]

kevin Abel wrote:. . . I know where this material is . . .

That's half the battle

I appreciate all of the time and effort . . .

That's a pleasure

[kevin Abel]

Junilu Lacar wrote: Another tip on style, when appropriate (which is probably the majority of the time), the first word of the JavaDoc comment should be a verb in the 3rd person declarative form (not 2nd person imperative) to convey the sense of an action taken.

(I didn't copy the code example from above. )

So prefer verb forms like "Calculates" and "Sets" over "Calculate" and "Set".

When I was looking at this post 3 years ago, I saw words such as :

3rd person declarative form (not 2nd person imperative)

I  was sent back to grade school memories where I didn't know what the teacher was talking about.    I think I understand it now.    

I should end verbs in comments with an "s".  So it says what it does

Don't use command words.

I recall something about third person being called "Fly on the wall"   I'm not even sure if that has to do with this.   I should have listened to my English teacher 50 years ago.  

Thanks,

Kevin

[Tim Holloway]

Strictly speaking. the essence of a class or method should be the first sentence of its JavaDoc comment. So you'd say "Does a foo." or "Manages a bar". And it must actually be a sentence (ending with a full-stop period). The JavaDoc compiler uses that first sentence when it you request the short synopsis view of the class or method.

Some examples:

/**
 * Service for taking an ingredients line, parsing it and
 * returning a populated Ingredients object. Understands fraction
 * characters in the amounts fields.
 * 
 * @author timh
 * @since Dec 1, 2021 TestedBy @see IngredientDigesterTest
 */
public class IngredientDigester {
...

And at the method level:

	/**
	 * Remove "noise" from ingredient title. For best results,
	 * should be adaptable for incoming language.
	 * 
	 * @param string Item string with noise.
	 * @return Item string with noise removed.
	 */
	private static String nonoise(String string) {