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.
kevin Abel wrote:. . . Is there logic that if I start using tags that I have to use them everyplace?
. . . Is the word after @param indicating the next word is the parameter that it is making a comment for?
Which book? Murach?
. . . . My book is showing this for voids:
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.
. . . You are saying not to use add parameter types. . . .
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?
kevin Abel wrote:I get error messages for methods that return void. If I don't include it then I get error messages.
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.
kevin Abel wrote:You are saying not to use add parameter types. How do I do this for voids?
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.
Which the book manages to disagree with.
. . . . don't bother repeating things that are already obvious, such as the return type.
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.
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.
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.
It's a flongler, something you flongle with
Mike Simmons wrote:. . . WTF is a flonger, anyway? . . .
Good idea, as long as it doesn't make the documentation harder to navigate. I don't think this sort of comment really helpful
. . .
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.
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.
Campbell Ritchie wrote:It's a flongler, something you flongle with
Apart from the fact that such comments may constrain you to keep the same implementation for ever.
Tim Holloway wrote:. . . If you must explain the inner workings, fine . . .
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.
the implementer Mike Duigou wrote:There are no plans to attempt to popularize these particular tags outside of use by JDK documentation.
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.
Junilu Lacar wrote:. . . a few examples of implementation specific notes . . . I'm too lazy to look right now . . .
That's half the battle
kevin Abel wrote:. . . I know where this material is . . .
That's a pleasure
I appreciate all of the time and effort . . .
You guys wanna see my fabulous new place? Or do you wanna look at this tiny ad?
Two software engineers solve most of the world's problems in one K&R sized bookhttps://coderanch.com/wiki/718759/books/Building-World-Backyard-Paul-Wheaton