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 >> > > > > >> > > > >> > > >> > >>
