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