Hi,
Stefan Guggisberg schrieb:
On Fri, 18 Mar 2005 16:30:34 +0100, Tobias Strasser
<[EMAIL PROTECTED]> wrote:
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.
@inheritDoc should also not be used in situations where the API spec leaves options, such as "implementation may do this or that". In this case the JavaDoc should explicitly state which option is taken.
For example the spec for Session.impersonate states "... Returns a new session in accordance with the specified (new) Credentials. Allows the current user to "impersonate" another using incomplete credentials (perhaps including a user name but no password, for example), assuming that their original session gives them that permission..." In this case, of course, it is crucial for the implementation to specify whether partial credentials are supported and what kind of credentials are required.
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?
+1 Couldn't the -link command line option to javadoc help ?
Regards Felix Meschberger
