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

No correct solution

Licensed under: CC-BY-SA with attribution
scroll top