Eric Lemings wrote:
-----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.
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
rw_printf.
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
readable).
Martin
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.
