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.
1
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.
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.
2