#70 Javadoc of overriding methods optional

closed
nobody
None
3
2012-10-10
2002-05-15
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.

     
  • Oleg Sukhodolsky

    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.

     
  • Oleg Sukhodolsky

    Logged In: YES
    user_id=746148

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

     
  • Andreas Schönknecht

    Logged In: YES
    user_id=545267

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

     
  • Oleg Sukhodolsky

    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?

     
  • Andreas Schönknecht

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

     
  • Oleg Sukhodolsky

    Logged In: YES
    user_id=746148

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

     
  • Thomas E. Wieger

    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.

     
  • Rudi Vankeirsbilck

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

     

Log in to post a comment.

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks