Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I'm currently writing an API and its documentation. For example I have something like this:

public interface Event {
}

public interface Process {
}

public interface EventProcessor {
    /**
     * Starts to process the sepcified event asynchronously. The returned
     * {@link Process} can be used to track progress on the processing. If the
     * specified event causes more {@link Event events} to be processed in this
     * system, then they are also tracked via the returned {@link Process}.
     * 
     * @param event
     *            to be started to process
     * @return
     */
    Process startProcessing(Event event);
}

In the example above, the javadoc link to the interface Process is repeated. In the API I'm writing there are cases where I have several more references to the same class in a single javadoc comment.

Should I always mark references to the class/method/etc. as javadoc links?

Generally, I think having many links in a javadoc comment is a sign for high cohesion. But when it's often the same target, which is linked, I'm not sure if this is good.

share|improve this question
1  
Have you reviewed Oracle's javadoc guidelines? oracle.com/technetwork/java/javase/documentation/… –  Aaron Kurtzhals May 24 '13 at 14:27
add comment

2 Answers 2

up vote 1 down vote accepted

Here is what the oracle javadoc guidelines say:

Use in-line links economically
You are encouraged to add links for API names (listed immediately above) using the {@link} tag. It is not necessary to add links for all API names in a doc comment. Because links call attention to themselves (by their color and underline in HTML, and by their length in source code doc comments), it can make the comments more difficult to read if used profusely. We therefore recommend adding a link to an API name if:

  • The user might actually want to click on it for more information (in your judgment), and
  • Only for the first occurrence of each API name in the doc comment (don't bother repeating a link)

Our audience is advanced (not novice) programmers, so it is generally not necessary to link to API in the java.lang package (such as String), or other API you feel would be well-known.

So summarized, repeating links to the same link target is a bad practice.

Thanks to @AaronKurtzhals for pointing me there.

share|improve this answer
add comment

I hate to be the one to tell you, but if you really (really) worry about repeating then it's irrelevant how many links will be there because no matter what, readers of generated javadocs will see text repeated twice:

...returned Process can be used to track progress on the processing. If the specified event causes more events to be processed in this system, then they are also tracked via the returned Process

So, prior to making complicated decisions to link or not to link, you better decide on basics: would you worry about repeating text or not?

  • If you decide not to worry about repeating text, then it really makes better sense not to worry about links - just use them the way that feels easier to you. Readers watching repeated text are unlikely to appreciate your efforts about consistency in presenting links in it.

If, on the other hand, you decide to rephrase docs to avoid repeating text, this will also resolve your concern about repeating links.

Just be careful here, because making good, easy to read, non-repetitive text may take quite a lot of effort. In that case, consider involving someone else to review your docs (generated, because these will look different from javadocs sources).

If you don't have a luxury of a reviewer, do self-reviews, that is wait for a day or two (better for a week or two), then review the docs yourself - fresh look will be almost (though not quite) like another pair of eyes.

share|improve this answer
1  
+ The structure of the comment is a bigger issue than the repeated links. Move notes concerning the return value to the section for notes on the return value. Move notes that concern each parameter to the section for each parameter. –  JustinC May 24 '13 at 20:12
    
Just because you've written your comments as JavaDoc doesn't mean people will always read them as the generated documentation. When reading the comments in the code directly, those links are a bit more clutter, reducing readability in a small but perhaps significant way. Irrespective of the generated documentation, I think there's some benefit to avoiding the redundancy and reducing the clutter - only including the link annotations where there's a real reason to do so. –  Steve314 May 26 '13 at 11:31
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.