On Fri, 18 Mar 2005 16:30:34 +0100, Tobias Strasser <[EMAIL PROTECTED]> wrote: > 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?
hmm, i'd prefer to stick to the @inheritDoc tags. i am not a javadoc expert but i am sure that there must be a way to include the jcr api sources (and others of course) so that those tags are resolved correctly. any ideas? cheers stefan > > 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 >--- >
