> -----Original Message----- > From: Martin Sebor [mailto:[EMAIL PROTECTED] > Sent: Friday, May 16, 2008 11:26 AM > To: [email protected] > Subject: Re: svn commit: r656686 - in > /stdcxx/branches/4.2.x/tests: include/rw_printf.h src/printf.h > > [EMAIL PROTECTED] wrote: > > Author: elemings > > Date: Thu May 15 07:45:54 2008 > > New Revision: 656686 > > > > URL: http://svn.apache.org/viewvc?rev=656686&view=rev > > Log: > > 2008-05-15 Eric Lemings <[EMAIL PROTECTED]> > > > > STDCXX-871 > > * tests/src/printf.h: Remove documentation-only header. > > * tests/include/rw_printf.h: Incorporate documentation comments > > from deleted header. > > So there now are two blocks documenting these directives > in the header, one above the rw_asnprintf() function and > another below it. Are you planning to consolidate them?
No, they should be kept separate since the comment above the function specifically documents the function itself and thus forms part of the API reference. The doc comments for formatting directives are technically also part of the API reference but apply to all printf-like functions. So I put them in the "Related Pages" section. There should however be a direct link to the formatting directives page from each function specification that accepts them. > > Also, since you chose to make heavy use of Doxygen markups, > do you have a plan WRT generating the Doxygen documention > for the driver? I do like the HTML generated from these > markups but I find the raw marked up text quite a bit harder > to read than the plain text comments without the markups. In the distribution, the process should work like this. There should be a "doc" target somewhere in the Makefiles that checks for the presence of doxygen and, if found, generates the documentation if not already built. As for the doc comments source, I personally don't like a lot of the Doxygen-specific directives and markup myself. My personal preference is to keep the doc comments in-line with Javadoc usage and conventions; e.g. use '/** ... */' or '///' comments, begin descriptions with a brief one-sentence summary, prefer HTML markup, do not use Doxygen-specific markup (use '@' instead of '!'), etc., etc. Marc already has some of this in writing I believe. I can supplement his "style guide" if it would help. The directives defining the outline of the formatting directives may look somewhat strange but these sorts of directives are not necessary for documenting the majority of the API. Most of the API doc comments should be quite readable even for readers that are not that familiar with Javadoc. Brad.
