About this question
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.
