jackrabbit-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Felix Meschberger <Felix.Meschber...@day.com>
Subject Re: @inheritDoc
Date Fri, 18 Mar 2005 16:01:26 GMT
Hi,

Stefan Guggisberg schrieb:

>On Fri, 18 Mar 2005 16:30:34 +0100, Tobias Strasser
><tobias.strasser@gmail.com> 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
>>{@inheritDoc} 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



Mime
View raw message