Target lines Javadoc

Question

I always write inline comments, until I learnt to use Javadoc. Now I was wondering, how can I effectively select a line and tell something about it in the Javadoc instead of an inline comment.

Example:
This is my void:

public void test() {
    //This is a test sentence
    String testSentence = "Test";
    //This is another test sentence
    String anotherTestSentence = "Test";
}

How I would do it if there is no other (more effective) method:

/**
 * @line 2 This is a test sentence
 * @line 3 This is another test sentence
 */
public void test() {
    String testSentence = "Test";
    String anotherTestSentence = "Test";
}

Does anyone know if there is indeed any better way, or that I should use inline comments instead of Javadoc? I noticed that @line did some weird things, but I can't find anything about it.

Answer 1

Javadoc is intended to document the API, not the implementation. You should avoid specifying implementation details in the Javadoc, because doing so limits your ability to change the implementation. Callers might begin to depend on the implementation details that you've documented.

Use Javadoc to document the proper use of a class or method, especially things that are not self-documenting, such as preconditions, postconditions, side effects, and exceptions, including runtime exceptions.

Answer 2

You cannot (at least not with the standard tag set).

First, @line is not a standard javadoc tag (see tag list below), and if you used it you would expect to see something along the lines of:

sourcefile.java:1234: warning - @line is an unknown tag.

Second, from the Oracle docs regarding placement of comments (emphasis mine):

Documentation comments are recognized only when placed immediately before class, interface, constructor, method, or field declarations -- see the class example, method example, and field example. Documentation comments placed in the body of a method are ignored.

So, unfortunately, there is no way to do this. There are no line-related tags, and there is no way to put javadoc comments inside method bodies.

The full syntax of comments as well as a list of supported tags is listed over at Oracle's javadoc documentation, in particular:

• Commenting the Source Code - Comment syntax.
• Javadoc Tags - Full list of supported tags.

(The Java 8 docs for the tool are there too, but nothing really changed, I just find the 7 documentation easier to browse.)

Additionally, philosophically, Kevin Krumwiede hits the nail on the head.

All that said you could probably create your own @line tag if you wanted, see the section on -tag and -taglet command line options here (-taglet is right below it). Perhaps your previous encounter with @line was somebody's custom tag. Custom tag or not, however, you would not be able to put the comments within the method body itself.

Be careful, though... in addition to the philosophical reasons to not do this, you'll also have to take care not to reference absolute line numbers in your documentation (be it a custom tag or just in general), because you will break all of your documentation as soon as you add/remove a line earlier on in the file. It will be a documentation maintenance nightmare.