stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Martin Sebor <>
Subject Re: svn commit: r656686 - in /stdcxx/branches/4.2.x/tests: include/rw_printf.h src/printf.h
Date Mon, 19 May 2008 22:30:27 GMT
Eric Lemings wrote:
>> -----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.

I'm not sure I follow what you're saying.

The original comment above rw_asnprintf() was meant to be where
all the directives were going to be documented. As STDCXX-871
points out, the documentation is missing a bunch of directives.
Your change adds a new block with documentation for some of the
previously undocumented directives, but also for some of those
that were there before. The new block is also incomplete. So,
AFAICS, we now have two blocks documenting the same concept in
two different ways with some overlap. I'm pretty sure you'll
agree that's not desirable. Worse, IMO, the current state of
the documentation of the directives is worse than before. We
need all the supported directives documented exactly once and
in the same place.

If we take the C99 standard as the guiding example, all the
directives would documented under one of the rw_printf()
functions (e.g., rw_fprintf()), and the documentation of
all the other functions would point to rw_fprintf() for
reference on the directives.

Alternatively, there could be a separate section for all
the directives, independent of any of the "overloads" of

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

That sounds like a good enhancement to the makefiles but it's
different from what I was asking about: how do we generate and
publish the docs on our site? Without online docs the Doxygen
markups are much less valuable (every contributor to the test
suite would have to generate their own local copy to make them


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

View raw message