[Hawkular-dev] Checkstyle javadoc settings

[Peter Palaga]

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