hi, a couple of days we started to replace our @see tags to @inheritDoc tags because we thought that this would be an easier way to inherit javadoc comments from a superclass or interface. this has one drawback: javadoc can only inherit the doc if the respective source code is also contained in the set of documented source files. this results in empty javadoc comments for such methods. eg:
http://incubator.apache.org/jackrabbit/apidocs/org/apache/jackrabbit/core/NodeImpl.html#addNode(java.lang.String) is empty, because the comment on javax.jcr.Node#addNode is not accessible anymore during the time of building the doc. i suggest: - to use @see tags for all comments where the superclass is not in the save project/source set. mainly for all classes implementing interfaces outside jackrabbit. - to use @inheritDoc only for comments for classes/method implementing or subclassing an interface/class within the jackrabbit project. - only use @inheritDoc, if the comment to inherit is known, and if it will fit as-is to the target location. examples: - when implementing an Iterator, it would be inaccurate to [EMAIL PROTECTED] the remove() method if the implementation always throws an UnsupportedOperationException. /** * Always throws UnsupportedOperationException */ public void remove() - when overriding Object.equals() or Object.hashCode(), the javadoc in the jdk is quite extensive and does not provide additional information for the overridden method. /* * Checks if this X and the given one are equal as described in [EMAIL PROTECTED] Object#equals(Object)}. * internally, the XX fields of the objects are compared. */ public boolean equals(Object obj) any comments on this? cheers, tobi -- ------------------------------------------< [EMAIL PROTECTED] >--- Tobias Strasser, Day Management AG, Barfuesserplatz 6, CH - 4001 Basel T +41 61 226 98 98, F +41 61 226 98 97 -----------------------------------------------< http://www.day.com >---
