jackrabbit-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Angela Schreiber <anch...@day.com>
Subject Re: @inheritDoc
Date Fri, 18 Mar 2005 17:15:33 GMT
hi tobi

i like your suggestions and would prefer it to general usage
of @inheritDoc, mostly from a developer perspective:

- i fear, that @inheritDoc is used for lazyness without
   checking, if the inherited documentation is meaningful in the
   given context...

- i appreciate the @see tag, since it makes very easy to
   understand, which interface defined them (so: general
   overview if you are new to the code). and second it allows
   to clean up code during development, if the interface
   is still a moving target.

your suggestion would offer a good balance. @inheritDoc,
whereever the developer is involved with the javadoc (same project),
@see if not. i would feel comfortable with that solution.


> 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.

View raw message