jackrabbit-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefan Guggisberg <stefan.guggisb...@gmail.com>
Subject Re: @inheritDoc
Date Fri, 18 Mar 2005 15:40:32 GMT
On Fri, 18 Mar 2005 16:30:34 +0100, Tobias Strasser
<tobias.strasser@gmail.com> 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
> {@inheritDoc} 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 {@link
> 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
> --
> ------------------------------------------< tobias.strasser@day.com >---
> 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 >---
>

Mime
View raw message