[ checkstyle-Feature Requests-556373 ] Javadoc of overriding methods optional

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

[ checkstyle-Feature Requests-556373 ] Javadoc of overriding methods optional

SourceForge.net
Feature Requests item #556373, was opened at 2002-05-15 08:01
Message generated for change (Comment added) made by oburn
You can respond by visiting:
https://sourceforge.net/tracker/?func=detail&atid=397081&aid=556373&group_id=29721

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
>Status: Closed
Priority: 3
Private: No
Submitted By: Robert Tansley (rtansley)
Assigned to: Nobody/Anonymous (nobody)
Summary: Javadoc of overriding methods optional

Initial Comment:
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.

----------------------------------------------------------------------

>Comment By: Oliver Burn (oburn)
Date: 2012-04-21 18:42

Message:
See the documentation for
http://checkstyle.sourceforge.net/config_javadoc.html#JavadocMethod

It supports the @Override tag to indicate that Javadoc is not required. Not
sure what release this added in

----------------------------------------------------------------------

Comment By: Rudi Vankeirsbilck (rudivk)
Date: 2011-11-26 11:50

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

----------------------------------------------------------------------

Comment By: Oliver Burn (oburn)
Date: 2005-07-04 16:44

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


----------------------------------------------------------------------

Comment By: Ken Arnold (kcrca)
Date: 2005-07-04 16:38

Message:
Logged In: YES
user_id=66520

Thanks, I'll await the next release.

----------------------------------------------------------------------

Comment By: Thomas E. Wieger (twieger)
Date: 2005-07-04 16:07

Message:
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

----------------------------------------------------------------------

Comment By: Oleg Sukhodolsky (o_sukhodolsky)
Date: 2004-09-14 00:25

Message:
Logged In: YES
user_id=746148

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

----------------------------------------------------------------------

Comment By: Lars Kühne (lkuehne)
Date: 2004-08-14 10:51

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


----------------------------------------------------------------------

Comment By: Andreas Schönknecht (schoolm)
Date: 2004-08-13 06:13

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

----------------------------------------------------------------------

Comment By: Oleg Sukhodolsky (o_sukhodolsky)
Date: 2004-08-13 04:11

Message:
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?

----------------------------------------------------------------------

Comment By: Andreas Schönknecht (schoolm)
Date: 2004-08-13 03:58

Message:
Logged In: YES
user_id=545267

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

----------------------------------------------------------------------

Comment By: Oleg Sukhodolsky (o_sukhodolsky)
Date: 2003-05-28 23:03

Message:
Logged In: YES
user_id=746148

Here is a link with description of automatic reuse of method comments -
http://java.sun.com/j2se/1.4.1/docs/tooldocs/windows/javadoc.html#inheritingcomments

----------------------------------------------------------------------

Comment By: Oleg Sukhodolsky (o_sukhodolsky)
Date: 2003-05-28 23:01

Message:
Logged In: YES
user_id=746148

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


----------------------------------------------------------------------

Comment By: Oleg Sukhodolsky (o_sukhodolsky)
Date: 2003-05-24 03:28

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


----------------------------------------------------------------------

Comment By: Ken Arnold (kcrca)
Date: 2002-07-02 12:56

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

----------------------------------------------------------------------

You can respond by visiting:
https://sourceforge.net/tracker/?func=detail&atid=397081&aid=556373&group_id=29721

------------------------------------------------------------------------------
For Developers, A Lot Can Happen In A Second.
Boundary is the first to Know...and Tell You.
Monitor Your Applications in Ultra-Fine Resolution. Try it FREE!
http://p.sf.net/sfu/Boundary-d2dvs2
_______________________________________________
Checkstyle-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/checkstyle-devel