James Tauber's Blog 2004/05/11
Inheriting Doc in Javadoc and Eclipse
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
by James Tauber : Created on May 11, 2004 : Last modified Feb. 8, 2005 : (permalink)