incubator-stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Eric Lemings" <>
Subject RE: svn commit: r656686 - in /stdcxx/branches/4.2.x/tests: include/rw_printf.h src/printf.h
Date Mon, 19 May 2008 17:03:15 GMT

> -----Original Message-----
> From: Martin Sebor [] 
> Sent: Friday, May 16, 2008 11:26 AM
> To:
> Subject: Re: svn commit: r656686 - in 
> /stdcxx/branches/4.2.x/tests: include/rw_printf.h src/printf.h
> wrote:
> > Author: elemings
> > Date: Thu May 15 07:45:54 2008
> > New Revision: 656686
> > 
> > URL:
> > Log:
> > 2008-05-15  Eric Lemings <>
> > 
> > 	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.


View raw message