There are three ways in Javadoc that you can reference interface doc from
implementations.
For a while I've favoured alternative A over alternative B because of the "inherited doc in Eclipse" issue. But there are still
disadvantages of this approach.
I recently discovered the {@inheritdoc} tag in Javadoc: alternative C. It's attractive, but it's a tough call because even though the only issue with it is the lack of inherited doc in Eclipse, that's a pretty big issue for me.
Right-click "Open Super Implementation" allows navigation up the tree to
see the superclass or interface's doc but it still doesn't help with tool
tips for calls to the implementation.
Alternative A: non-Javadoc @see reference
Pros:
- inherited doc in Eclipse
- inherited doc in Javadoc
Cons:
- reported as missing Javadoc comment in Checkstyle
- Javadoc can't check reference
- additional doc specific to this implementation will not appear in Javadoc
Alternative B: Javadoc @see reference
Pros:
- satisfies Checkstyle requirement for Javadoc
- Javadoc can check reference
- additional doc specific to this implementation will appear in Javadoc
Cons:
- no inherited doc in Eclipse
- no inherited doc in Javadoc
Alternative C: Javadoc {@inheritdoc}
Pros:
- satisfies Checkstyle requirement for Javadoc
- no references to go stale
- additional doc specific to this implementation will appear in Javadoc
- inherited doc in Javadoc
Cons:
- no inherited doc in Eclipse