jackrabbit-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tobias Strasser <tobias.stras...@gmail.com>
Subject @inheritDoc
Date Fri, 18 Mar 2005 15:30:34 GMT
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?

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