[Hawkular-dev] Checkstyle javadoc settings

[Thomas Segismont]

There's also "allowMissingJavadoc". I'm +1 for adding Javadoc checks 
provided we don't fail the build on missing 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.

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
>