[Hawkular-dev] Checkstyle javadoc settings

Wed Feb 4 08:30:59 EST 2015

Le 04/02/2015 13:49, Peter Palaga a écrit :
> On 02/04/2015 10:57 AM, Thomas Segismont wrote:
>> There's also "allowMissingJavadoc". I'm +1 for adding Javadoc checks
>> provided we don't fail the build on missing Javadoc.
>
> Not failing and just having the warnings in the build log is useless.

There's a misunderstanding: I'm talking about not failing the build if a 
single method does not have Javadoc.

If a method has Javadoc which does not represent reality (wrong list of 
parameters for example) then yes, the build should fail.

> What is not enforced, will be ignored.

That's not my opinion.

> I am against introducing anything that can be ignored or overseen to checkstyle.

See my first comment, I'm talking about not failing the build if a 
single method does not have Javadoc.

>
>> It's not just
>> getters/setters: sometimes your method has a meaningful name and it does
>> not make any sense to write Javadoc for it.
>
> I do not believe that something like this can be configured with
> Checkstyle.

Isn't that the purpose of "allowMissingJavadoc"?

>
> However given that the general idea of adding JavaDoc checks has become
> some level of support here, Gary or anybody else, feel free to submit a
> PR to our checkstyle.xml [1] plus do not forget to test your proposal
> with metrics, bus and alerts.
>
> [1]
> https://github.com/hawkular/hawkular-build-tools/blob/master/src/main/resources/hawkular-checkstyle/checkstyle.xml
>
>
> -- P
>
>> Le 04/02/2015 10:02, Gary Brown a écrit :
>>> Hi
>>>
>>> According to the docs
>>> (http://checkstyle.sourceforge.net/config_javadoc.html#JavadocMethod)
>>> the 'allowMissingPropertyJavadocs' parameter can be used to skip
>>> checking of getters/setters.
>>>
>>> Regards
>>> Gary
>>>
>>> ----- Original Message -----
>>>> Hey,
>>>>
>>>> I am in favor of JavaDoc and having some checking - especially as in
>>>> RHQ we
>>>> have many places
>>>> where the param list of a method and the one in JavaDoc have
>>>> diverged over
>>>> time.
>>>>
>>>> I am not in favor of forcing javadoc on every method (especially
>>>> getter/setter), as this will just end up in
>>>>
>>>> /** This is the getter for foo */
>>>> public foo getFoo() {}
>>>>
>>>> Which is imo worse than no doc.
>>>>
>>>> Unfortunately I think the default for JavaDoc is not to document
>>>> private
>>>> properties (=not include in the generated html),
>>>> so that putting the comment on the property itself does not help for
>>>> browsing
>>>> docs.
>>>>
>>>>
>>>>
>>>>
>>>>> Am 04.02.2015 um 09:34 schrieb Gary Brown <gbrown at redhat.com>:
>>>>>
>>>>> Hi Peter
>>>>>
>>>>> The main reason I mentioned it was because although I had been
>>>>> diligent in
>>>>> Overlord re javadoc, once the rule was enabled it picked up many
>>>>> issues -
>>>>> primarily inconsistency between parameter names, or missing parameter
>>>>> entries.
>>>>>
>>>>> I agree meaningful text can only be picked up by review, but think
>>>>> that
>>>>> areas where automated checking is possible shouldn't be part of the
>>>>> reviewers responsibility (i.e. to reduce their burden so they can
>>>>> focus on
>>>>> other areas).
>>>>>
>>>>> Regards
>>>>> Gary
>>>>>
>>>>> ----- Original Message -----
>>>>>>> Not sure if this was previously discussed and decided
>>>>>>
>>>>>> Not that I knew. We decided to start from a very minimal set of rules
>>>>>> that we initially copied from wildfly. We have not changed much:
>>>>>> we just
>>>>>> increased the line length to 120 chars and extended the plaintext
>>>>>> checks
>>>>>> to non-java files.
>>>>>>
>>>>>> I am personally undecided about JavaDoc checks. Having a meaningful
>>>>>> JavaDoc is a good thing.
>>>>>> Checkstyle can certainly help to some extent, but:
>>>>>> (1) It is not enough as it will never check the meaningfulness
>>>>>> (2) I tend to believe that some methods (incl. getters and
>>>>>> setters) do
>>>>>> not need JavaDoc
>>>>>> (3) Non-public methods often should have JavaDoc too.
>>>>>>
>>>>>> I am a strong proponent of four eyes principle: no single commit
>>>>>> can go
>>>>>> to master without being reviewed properly. It should be reviewer's
>>>>>> responsibility to check test coverage, JavaDoc, etc.
>>>>>>
>>>>>> Best wishes,
>>>>>>
>>>>>> -- Peter
>>>>>>
>>>>>> On 02/03/2015 07:19 PM, Gary Brown wrote:
>>>>>>> It checks presence of javadoc, and matching entries for
>>>>>>> parameters and
>>>>>>> return values.
>>>>>>>
>>>>>>> ----- Original Message -----
>>>>>>>> Does this just look to see if all public methods have SOME javadoc?
>>>>>>>> (i.e.
>>>>>>>> it
>>>>>>>> just sees if they are missing)
>>>>>>>>
>>>>>>>> Does it impose some type of formatting as well?
>>>>>>>>
>>>>>>>> ----- Original Message -----
>>>>>>>>> Hi
>>>>>>>>>
>>>>>>>>> Just started using the hawkular parent pom and noticed that the
>>>>>>>>> checkstyle
>>>>>>>>> config does not check the javadoc comments.
>>>>>>>>>
>>>>>>>>> Not sure if this was previously discussed and decided that it
>>>>>>>>> shouldn't
>>>>>>>>> be
>>>>>>>>> checked, but thought I had better check, as this is one area
>>>>>>>>> that can
>>>>>>>>> be
>>>>>>>>> time consuming to update code after enabling.
>>>>>>>>>
>>>>>>>>> Previously I had been using this config in Overlord:
>>>>>>>>> https://github.com/Governance/overlord-commons/blob/master/overlord-commons-build/src/main/resources/checkstyle/checkstyle.xml#L83-L97
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> Regards
>>>>>>>>> Gary
>>>>>>>>> _______________________________________________
>>>>>>>>> hawkular-dev mailing list
>>>>>>>>> hawkular-dev at lists.jboss.org
>>>>>>>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>>>>>>>>>
>>>>>>>> _______________________________________________
>>>>>>>> hawkular-dev mailing list
>>>>>>>> hawkular-dev at lists.jboss.org
>>>>>>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>>>>>>>>
>>>>>>> _______________________________________________
>>>>>>> hawkular-dev mailing list
>>>>>>> hawkular-dev at lists.jboss.org
>>>>>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>>>>>>>
>>>>>>
>>>>>>
>>>>> _______________________________________________
>>>>> hawkular-dev mailing list
>>>>> hawkular-dev at lists.jboss.org
>>>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>>>>
>>>> --
>>>> Reg. Adresse: Red Hat GmbH, Technopark II, Haus C,
>>>> Werner-von-Siemens-Ring 14, D-85630 Grasbrunn
>>>> Handelsregister: Amtsgericht München HRB 153243
>>>> Geschäftsführer: Charles Cachera, Michael Cunningham, Paul Hickey,
>>>> Charlie
>>>> Peters
>>>>
>>>>
>>>> _______________________________________________
>>>> hawkular-dev mailing list
>>>> hawkular-dev at lists.jboss.org
>>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>>>>
>>>
>>> _______________________________________________
>>> hawkular-dev mailing list
>>> hawkular-dev at lists.jboss.org
>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>>>
>>
>> _______________________________________________
>> hawkular-dev mailing list
>> hawkular-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>>
>