You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Oliver Heger <ol...@t-online.de> on 2005/10/05 21:02:57 UTC
[configuration] Checkstyle
I am having some fun fixing the numerous Checkstyle warnings.
One warning that is displayed very often is "Missing a Javadoc comment".
For Javadoc itself this is not much of a problem because the tool knows
how to inherit the comments from super classes or implemented
interfaces. But Checkstyle wants an explicit comment (the @inheritDoc
tag is not recognized either).
Personally I prefer to have Javadocs for all methods. This makes the
code more readable. But it would be a bunch of work to fix this now.
Other opinions? How is this handled by other components?
Oliver
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [configuration] Checkstyle
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Oliver Heger wrote:
> Personally I prefer to have Javadocs for all methods. This makes the
> code more readable. But it would be a bunch of work to fix this now.
There is
http://sourceforge.net/projects/jdochelper
and various other stuff on the 'forge which might help, as
usual. I haven't have time to try it out though (if you do,
please post to community@ or general@jakarta or something
if you like it).
I personally would find it useful to turn checkstyle into
a stream editor which also fixes style errors which can be
fixed automatically, like file headers, JavaDoc templates,
indentation and brace style and so on.
HTH
J.Pietschmann
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [configuration] Checkstyle
Posted by Thomas Dudziak <to...@gmail.com>.
On 10/7/05, Dennis Lundberg <de...@mdh.se> wrote:
> Thomas Dudziak wrote:
> > On 10/6/05, Jörg Gottschling <jo...@myndian.de> wrote:
> >
> >>I think patching Checkstyle would be the better way.
> >
> >
> > Good luck! I had a look at their feature request page, and there were
> > entries from over a year ago.
>
> The Checkstyle team are usually responsive to RFE's with patches. As
> long as the feature doesn't break the Checkstyle design.
Oh, I didn't say anything against the Checkstyle guys, rather I think
they are simply a bit overwhelmed by feature requests.
Tom
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [configuration] Checkstyle
Posted by Dennis Lundberg <de...@mdh.se>.
Thomas Dudziak wrote:
> On 10/6/05, Jörg Gottschling <jo...@myndian.de> wrote:
>
>>I think patching Checkstyle would be the better way.
>
>
> Good luck! I had a look at their feature request page, and there were
> entries from over a year ago.
The Checkstyle team are usually responsive to RFE's with patches. As
long as the feature doesn't break the Checkstyle design.
--
Dennis Lundberg, who hangs around on the checkstyle-devel list too.
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [configuration] Checkstyle
Posted by Thomas Dudziak <to...@gmail.com>.
On 10/6/05, Emmanuel Bourg <eb...@apache.org> wrote:
> Thomas Dudziak wrote:
> > Btw, I think this check is actually a good idea (including
> > @inheritDoc), because it forces the developer(s) to think about
> > Javadoc which IMO is quite important for a library developed by
> > multiple persons.
>
> True, but the rule could be twisted to something like "Raise a warning
> if the method has no javadoc and it doesn't override a method already
> documented in a super class".
Yes, well, but this way even the Javadoc tool will probably raise the
warning (didn't try it though), no need for checkstyle.
> > And adding an @inheritDoc doesn't cost much time, even if in 200
> > source files, and also has the benefit that it catches (hard-to-find)
> > bugs where the base-class method signature was changed but not the one
> > of the sub-class method.
>
> For some reason IntelliJ doesn't like this tag, I don't know for the
> other IDEs.
Hmm, its a standard tag of Javadoc in at least 1.4.2 and above
(http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#{@inheritDoc}).
Tom
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [configuration] Checkstyle
Posted by Emmanuel Bourg <eb...@apache.org>.
Thomas Dudziak wrote:
> Btw, I think this check is actually a good idea (including
> @inheritDoc), because it forces the developer(s) to think about
> Javadoc which IMO is quite important for a library developed by
> multiple persons.
True, but the rule could be twisted to something like "Raise a warning
if the method has no javadoc and it doesn't override a method already
documented in a super class".
> And adding an @inheritDoc doesn't cost much time, even if in 200
> source files, and also has the benefit that it catches (hard-to-find)
> bugs where the base-class method signature was changed but not the one
> of the sub-class method.
For some reason IntelliJ doesn't like this tag, I don't know for the
other IDEs.
Emmanuel Bourg
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [configuration] Checkstyle
Posted by Thomas Dudziak <to...@gmail.com>.
On 10/6/05, Jörg Gottschling <jo...@myndian.de> wrote:
> I think patching Checkstyle would be the better way.
Good luck! I had a look at their feature request page, and there were
entries from over a year ago.
Btw, I think this check is actually a good idea (including
@inheritDoc), because it forces the developer(s) to think about
Javadoc which IMO is quite important for a library developed by
multiple persons.
And adding an @inheritDoc doesn't cost much time, even if in 200
source files, and also has the benefit that it catches (hard-to-find)
bugs where the base-class method signature was changed but not the one
of the sub-class method.
Tom
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [configuration] Checkstyle
Posted by Jörg Gottschling <jo...@myndian.de>.
I think patching Checkstyle would be the better way.
--
Jörg Gottschling
web: www.myndian.de
eMail: jogi@myndian.de joerg@myndian.de
GnuPG: 0x9B1C64BB
ICQ: 177003788
Jabber: jogi@amessage.de
Skype: joerggottschling
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [configuration] Checkstyle
Posted by "Henning P. Schmiedehausen" <hp...@intermeta.de>.
Emmanuel Bourg <eb...@apache.org> writes:
If you are bothered about the Javadoc warnings, run the code through
Jalopy; it will fix up the javadocs with stubs containing the
parameters, return types and exceptions.
Best regards
Henning
>Oliver Heger wrote:
>> I am having some fun fixing the numerous Checkstyle warnings.
>>
>> One warning that is displayed very often is "Missing a Javadoc comment".
>> For Javadoc itself this is not much of a problem because the tool knows
>> how to inherit the comments from super classes or implemented
>> interfaces. But Checkstyle wants an explicit comment (the @inheritDoc
>> tag is not recognized either).
>>
>> Personally I prefer to have Javadocs for all methods. This makes the
>> code more readable. But it would be a bunch of work to fix this now.
>>
>> Other opinions? How is this handled by other components?
>I would not bother with these warnings, duplicating the javadoc in the
>subclasses is a pain to maintain and brings no benefit on code
>readability. With modern IDEs the description on the parent method is
>just one click away. I did put the @inheritDoc tags some time ago, but I
>don't think that was really a better choice.
>IMHO I would just drop these javadocs.
>Emmanuel Bourg
>---------------------------------------------------------------------
>To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
>For additional commands, e-mail: commons-dev-help@jakarta.apache.org
--
Dipl.-Inf. (Univ.) Henning P. Schmiedehausen INTERMETA GmbH
hps@intermeta.de +49 9131 50 654 0 http://www.intermeta.de/
RedHat Certified Engineer -- Jakarta Turbine Development -- hero for hire
Linux, Java, perl, Solaris -- Consulting, Training, Development
4 - 8 - 15 - 16 - 23 - 42
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [configuration] Checkstyle
Posted by Emmanuel Bourg <eb...@apache.org>.
Oliver Heger wrote:
> I am having some fun fixing the numerous Checkstyle warnings.
>
> One warning that is displayed very often is "Missing a Javadoc comment".
> For Javadoc itself this is not much of a problem because the tool knows
> how to inherit the comments from super classes or implemented
> interfaces. But Checkstyle wants an explicit comment (the @inheritDoc
> tag is not recognized either).
>
> Personally I prefer to have Javadocs for all methods. This makes the
> code more readable. But it would be a bunch of work to fix this now.
>
> Other opinions? How is this handled by other components?
I would not bother with these warnings, duplicating the javadoc in the
subclasses is a pain to maintain and brings no benefit on code
readability. With modern IDEs the description on the parent method is
just one click away. I did put the @inheritDoc tags some time ago, but I
don't think that was really a better choice.
IMHO I would just drop these javadocs.
Emmanuel Bourg
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org