Re: [Hawkular-dev] Checkstyle javadoc settings

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