We don't enforce much semantic consistency on our comments today. We follow the Google style guide, and cpplint.py (tied to our 'make lint' target) can enforce some stuff, but I don't think it does much, though I'm not sure; I haven't really played around with it. So yeah, if we enforce anything it's during code review, and that turns out to be tedious and time consuming for everyone involved. Take a look at cpplint.py; maybe it's got some checks that we're not running that'd yield better consistency.
On Thu, Jun 9, 2016 at 11:51 AM, Alexey Serbin <aser...@cloudera.com> wrote: > Adar, > > I concur -- noisy and useless comments is an issue if not taken care of. > > BTW, what about current comments in the code -- how is semantic consistency > being enforced? I would think it's more about code-review time; would not > expect much automation there. As for the style, I also think style-checker > would be great to have. Let's see what I can find out there. I remember > there were some tools (vera++, etc.). From that regard I really like Go > lang approach on this :) > > Let me provide a snippet/sample of how that doxygen-styled comments would > look like with current code and we can start from that. > > > Thanks, > > Alexey > > > > On Thu, Jun 9, 2016 at 10:21 AM, Adar Dembo <a...@cloudera.com> wrote: > >> I agree with Mike. In my experience Doxygen-style documentation can be >> very noisy in that it forces developers to write reams upon reams of >> "obvious" documentation (i.e. adding a line for a @return that is >> completely self-explanatory). >> >> I'm open to the idea of using it for public headers provided: >> - It's easy to draw the line between those files and the rest of the >> codebase. >> - We have some script to automate checking the Doxygen style on those >> files. >> >> I'd also like us spend some time discussing which aspects of Doxygen >> are worth implementing and which are excessive. Alexey, could you >> drive this discussion? Not sure if it makes more sense to do it over a >> sample patch (to e.g. client.h) or in a vacuum, whatever you think is >> best. >> >> On Thu, Jun 9, 2016 at 9:57 AM, Alexey Serbin <aser...@cloudera.com> >> wrote: >> > Hi All, >> > >> > Thank you for sharing your thoughts on this. >> > >> > From what I see the consensus is that for client API C++ headers it makes >> > sense to re-format in-code documentation to be in doxygen style. So, I'm >> > thinking about discussing style-related questions with Mike Percy and >> > others, preparing a patch and sending it for review. >> > >> > I think it's worth publishing the auto-generated results (HTML) along >> with >> > client Java API docs. Misty, what help is needed there? >> > >> > >> > Thanks, >> > >> > Alexey >> > >> > On Thu, Jun 9, 2016 at 9:37 AM, Misty Stanley-Jones < >> > mstanleyjo...@cloudera.com> wrote: >> > >> >> I'm +1 too. Do we want to publish these as HTML like we do with Javadoc >> >> too? If so, who wants to volunteer to help me figure that out? >> >> >> >> On Thu, Jun 9, 2016 at 8:28 AM, Sameer Abhyankar < >> sabhyan...@cloudera.com> >> >> wrote: >> >> >> >> > +1 for the client facing APIs! >> >> > >> >> > Sameer Abhyankar >> >> > Cloudera, Inc. >> >> > (404) 431-7806 >> >> > sam...@cloudera.com >> >> > >> >> > >> >> > >> >> > On Wed, Jun 8, 2016 at 10:25 PM, Mike Percy <mpe...@apache.org> >> wrote: >> >> > >> >> > > Hey Alexey, >> >> > > Glad you brought it up. I'm inclined to agree that this would be >> >> helpful >> >> > > for users of the C++ client APIs. >> >> > > >> >> > > But... I'm hesitant to do it for the rest of the code base. It can >> be >> >> > > pretty noisy, requires ongoing maintenance, and honestly I don't >> think >> >> it >> >> > > is helpful if you have decent dev tools set up (good editor with >> good >> >> > > plugins, ack / ag, etc) >> >> > > >> >> > > If we adopt Doxygen, I think we should agree on a particular style >> and >> >> > > adhere to it. >> >> > > >> >> > > Mike >> >> > > >> >> > > >> >> > > On Wed, Jun 8, 2016 at 6:00 PM, Dan Burkert <d...@cloudera.com> >> wrote: >> >> > > >> >> > > > +1 from me for at least doing it in client.h and the few other >> public >> >> > > > header files. These files have pretty much settled down, so it >> >> > shouldn't >> >> > > > be too onerous to keep the doxygen comments up to date once they >> are >> >> > > > created. >> >> > > > >> >> > > > - Dan >> >> > > > >> >> > > > On Wed, Jun 8, 2016 at 4:36 PM, Alexey Serbin < >> aser...@cloudera.com> >> >> > > > wrote: >> >> > > > >> >> > > > > Hi All, >> >> > > > > >> >> > > > > Looking at current documentation for Kudu client API at >> >> getkudu.org >> >> > > > > you can see that Java API has auto-generated documentation >> >> > > > > but C++ API does not. >> >> > > > > >> >> > > > > Adding doxygen-style comments into C++ header files would >> >> > > > > allow to auto-generate API documentation for C++ client API as >> >> well. >> >> > > > > >> >> > > > > Assuming doxygen-formatted comments are not considered >> >> > > > > as a violation of current C++ coding style, >> >> > > > > would it make sense to introduce doxygen-style comments >> >> > > > > for C++ client API headers? >> >> > > > > >> >> > > > > If it's worth it, in-line documentation in other parts of the >> C++ >> >> > code >> >> > > > base >> >> > > > > could be re-formatted into doxygen style as well. >> >> > > > > >> >> > > > > What do you think? >> >> > > > > >> >> > > > > Thank you! >> >> > > > > >> >> > > > > >> >> > > > > Best regards, >> >> > > > > >> >> > > > > Alexey >> >> > > > > >> >> > > > >> >> > > >> >> > >> >> >>
