[Hawkular-dev] Checkstyle javadoc settings

[Gary Brown]

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