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