Re: [Hawkular-dev] Checkstyle javadoc settings

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(a)redhat.com&gt;: >> >> 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-commo... >>>>>> >>>>>> Regards >>>>>> Gary >>>>>> _______________________________________________ >>>>>> hawkular-dev mailing list >>>>>> hawkular-dev(a)lists.jboss.org >>>>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev >>>>>> >>>>> _______________________________________________ >>>>> hawkular-dev mailing list >>>>> hawkular-dev(a)lists.jboss.org >>>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev >>>>> >>>> _______________________________________________ >>>> hawkular-dev mailing list >>>> hawkular-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev >>>> >>> >>> >> _______________________________________________ >> hawkular-dev mailing list >> hawkular-dev(a)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(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hawkular-dev > _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev