Is repeating javadocs links to file a bad practice?
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 specified 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.
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 colour 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 judgement), 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 summarised, repeating javadocs links to files is a bad practice.