[Hawkular-dev] Checkstyle javadoc settings

[Gary Brown]

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
>