Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

#70 Javadoc of overriding methods optional

closed
nobody
None
3
2012-10-10
2002-05-15
Robert Tansley
No

If you're overriding a method in a subclass, or
implementing an interface method, javadoc will use the
comment from the overridden method if you don't supply
a new one.

It would be good if you could avoid getting a "method
is missing a Javadoc comment" warning in this case.

Discussion

  • Ken Arnold
    Ken Arnold
    2002-07-02

    Logged In: YES
    user_id=66520

    With 1.4 one can also inherit @param, @return, and @throws clauses from the overidden method's doc. So it is valid to provide a doc comment body only and inherit some or all of these tags.

     
  • Logged In: YES
    user_id=746148

    There is an easy workaround which JavadocMethod check
    supports
    (Checkstyle 3.0 and later):
    Just use @see or {@inheritDoc} tags. For example:
    / @see com.puppycrawl.tools.checkstyle.Verifier /
    public int checkReturnTag(final int aTagIndex,
    JavadocTag[] aTags,
    int aLineNo)
    or
    / {@inheritDoc} /
    public int checkReturnTag(final int aTagIndex,
    JavadocTag[] aTags,
    int aLineNo)

    (See documentation for JavadocMethod for more information)

    I think it's easy enough and also much better then do not write
    javadoc at all, because such a comment makes java-code
    more clear for person who read it.

     
  • Logged In: YES
    user_id=746148

    bug#730372 (inherited javadoc comments) was closed as duplicate of this rfe.

     
  • Logged In: YES
    user_id=545267

    Is there any chance that this RFE will be implemented in one
    of the next versions?

     
  • Logged In: YES
    user_id=746148

    Perhaps the fastest way to get implementation of this RFE in
    checkstyle code is to implement it yourselves :(
    I personally fine with inheritDoc tag.
    Why you don't want to use suggested workaround?

     
  • Logged In: YES
    user_id=545267

    We would like to use Checkstyle in our whole Java
    development team and not only on a voluntary-basis. As you
    can imagine there is some resistance from the developers to
    overcome which becomes more difficult with each little thing
    that means additional work for them.

     
  • Lars Kühne
    Lars Kühne
    2004-08-14

    Logged In: YES
    user_id=401384

    Andreas, I can understand your point. However, we're all
    busy people and we do not get paid for working on
    checkstyle, so we usually implement an RFE because it
    scratches one of our own itches or because it's an
    interesting problem where we can learn something (e.g. learn
    about JDK 1.5 by adding support for it in checkstyle).

    I see one technical problem with this particular RFE:
    inheritance only works well if javadoc has access to the
    sources of the superclass, right? How does the javadoc check
    know about source availability? Should there be a package
    prefix parameter that you can set to your company's base
    package (assumeSourceAccess="de.yourcompany")?

    If that is sufficient, I think this RFE is probably not too
    difficult to implement. I'd suggest to follow Oleg's
    suggestion and dive right in to our sources. Who knows,
    maybe you'll submit more improvements over time and at some
    point the checkstyle team can welcome a new committer...

     
  • Logged In: YES
    user_id=746148

    1002845 (JavadocMethod: methods that inherit JavaDoc) was
    closed as duplicate of this RFE

     
  • Logged In: YES
    user_id=705849

    i have enhanced the JavadocMethodCheck to not complain about
    missing javadoc comments, when a method implements a method
    of an interface or overwrites a method from a superclass.
    if you would be interested i can provide a patch.

    best regards

    thomas

     
  • Ken Arnold
    Ken Arnold
    2005-07-04

    Logged In: YES
    user_id=66520

    Thanks, I'll await the next release.

     
  • Oliver Burn
    Oliver Burn
    2005-07-04

    Logged In: YES
    user_id=218824

    of course, always interested in getting patches. Ideally the
    patch should:
    - be based off CVS HEAD
    - include unit tests
    - include documentation.

     
  • If this issue was apparently already patched in 2005 (as the comments below suggest), can anybody tell me in which release this was published?