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 <[email protected]> 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 <[email protected]> > 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 < > > [email protected]> 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 < > [email protected]> > >> wrote: > >> > >> > +1 for the client facing APIs! > >> > > >> > Sameer Abhyankar > >> > Cloudera, Inc. > >> > (404) 431-7806 > >> > [email protected] > >> > > >> > > >> > > >> > On Wed, Jun 8, 2016 at 10:25 PM, Mike Percy <[email protected]> > 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 <[email protected]> > 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 < > [email protected]> > >> > > > 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 > >> > > > > > >> > > > > >> > > > >> > > >> >
