You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@stdcxx.apache.org by el...@apache.org on 2008/05/15 16:45:54 UTC
svn commit: r656686 - in /stdcxx/branches/4.2.x/tests: include/rw_printf.h
src/printf.h
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 <er...@roguewave.com>
STDCXX-871
* tests/src/printf.h: Remove documentation-only header.
* tests/include/rw_printf.h: Incorporate documentation comments
from deleted header.
Removed:
stdcxx/branches/4.2.x/tests/src/printf.h
Modified:
stdcxx/branches/4.2.x/tests/include/rw_printf.h
Modified: stdcxx/branches/4.2.x/tests/include/rw_printf.h
URL: http://svn.apache.org/viewvc/stdcxx/branches/4.2.x/tests/include/rw_printf.h?rev=656686&r1=656685&r2=656686&view=diff
==============================================================================
--- stdcxx/branches/4.2.x/tests/include/rw_printf.h (original)
+++ stdcxx/branches/4.2.x/tests/include/rw_printf.h Thu May 15 07:45:54 2008
@@ -160,4 +160,186 @@
rw_asnprintf (char** pbuf, _RWSTD_SIZE_T *pbufsize, const char *fmt, ...);
+/**
+ * @page rwtest-fmtspec Formated Output Directives and Conversion Specifiers
+ *
+ * The RWTest library supports all formatted output directives specified
+ * by the C99 standard as well as many other directive extensions. Only
+ * deviations, extensions, and other implmementation-defined behavior are
+ * described below. Consult your system and/or compiler documentation
+ * for specifications of the standard formatting output directives.
+ *
+ * Unless specified otherwise, the following caveats apply to all
+ * directives and conversions. Directives that accept a pointer argument
+ * will convert a null pointer into the string literal <tt>(null)</tt>.
+ *
+ *
+ * @section rwtest-fmtspec-c89 C89 Directives
+ *
+ * @subsection rwtest-fmtspec-c89-ptr Pointer \%p \%\#p
+ *
+ * The argument is a pointer to \c void. The value of the pointer is
+ * converted to a sequence of hexadecimal digits. The number of
+ * converted digits depends on the size of the \c void* type. The
+ * "alternate form" expressed by \c \%\#p immediately precedes converted
+ * digits with a \c 0x prefix.
+ *
+ *
+ * @section rwtest-fmtspec-c99 C99 Directives
+ *
+ * No known deviations or implementation-defined behavior.
+ *
+ *
+ * @section rwtest-fmtspec-ext RWTest Extensions
+ *
+ * @subsection rwtest-fmtspec-ext-bool Boolean \%b
+ *
+ * The argument is a value convertible to \c bool type. If the value
+ * of the argument is nonzero, the value is converted to the string
+ * literal \c true. Otherwise, the value converts to \c false.
+ *
+ * @subsection rwtest-fmtspec-ext-esc-c Escaped Character \%{c} \%{\#c}
+ *
+ * The argument is an integer value converted to <tt>unsigned char</tt>
+ * type. For non-printable characters, the resulting output is formatted
+ * as the corresponding escape sequence. (The value for a horizontal
+ * tab character for example is formatted as the string literal
+ * <tt>\\t</tt> and a zero value may be formatted as the string literal
+ * <tt>\\x00</tt>. In the alternate form, the resulting output is
+ * immediately surrounded with a single quotation mark <tt>'</tt>.
+ *
+ * @subsection rwtest-fmtspec-ext-esc-lc Escaped Wide Character \%{lc} \%{\#lc}
+ *
+ * Similar to the escaped character directive <tt>%{c}</tt> and quoted
+ * escaped character directive <tt>%{\#c}</tt> respectively, except
+ * that the argument is a value of <tt>wchar_t</tt> type.
+ *
+ * @subsection rwtest-fmtspec-ext-s Quoted Character String \%{\#s}
+ *
+ * Similar to the character string directive <tt>%s</tt> except that the
+ * resulting output is surrounded with a double quotation mark <tt>"</tt>.
+ *
+ * @subsection rwtest-fmtspec-ext-ls Quoted Wide Character String \%{\#ls}
+ *
+ * Similar to the quoted character string directive <tt>%{\#s}</tt>
+ * except that the argument is a pointer to a null-terminate sequence of
+ * <tt>wchar_t</tt> type.
+ *
+ * @subsection rwtest-fmtspec-ext-err Error Code \%m \%{\#m}
+ *
+ * The argument is an integer value representing a system-dependent error
+ * code. In the first form, the value is interpreted as an argument of
+ * the \c strerror() function. The formatted result is the return value
+ * of this function using this parameter value. In the second form, the
+ * formatted result is a character sequence representing the
+ * corresponding error name (e.g. \c ENOMEM) if applicable or equivalent
+ * numeric sequence in decimal notation otherwise.
+ *
+ * @subsection rwtest-fmtspec-ext-sig Signal \%K
+ *
+ * The argument is an integer value representing a system-dependent
+ * signal. The resulting output is a character sequence representing
+ * the name of corresponding signal (e.g. \c SIGABRT) if
+ * applicable or equivalent numeric sequence in decimal notation
+ * otherwise.
+ *
+ * @subsection rwtest-fmtspec-ext-bits Bitset \%{b}
+ *
+ * The argument is a pointer to an array of \c char. NOT YET COMPLETE
+ *
+ * @subsection rwtest-fmtspec-ext-Ai Integer Array \%{Ao} \%{Ad} \%{Ax}
+ *
+ * The argument is a pointer to an array of integer type. The resulting
+ * output is formatted as a string of comma-separated integer values.
+ * The notation of each integer value is specified by <tt>o</tt> for
+ * octal, <tt>d</tt> for decimal, or <tt>x</tt> for hexadcimal. An
+ * optional field width specifies the size of elements in the array
+ * (defaults to 1). An optional precision specifies the length of the
+ * array. In the alternate form, the resulting output for octal and
+ * hexidecimal integer values are prefixed with string literals
+ * <tt>0</tt> and <tt>0x</tt> respectively.
+ *
+ * @subsection rwtest-fmtspec-ext-Is Stream State \%{Is} \%{\#Is}
+ *
+ * The argument is a value of type <tt>std::ios_base::iostate</tt>. In
+ * the plain form, the resulting ouput is formatted as a sequence of one
+ * or more unqualified names corresponding to the \c iostate enumerators,
+ * separated by the OR operator (<tt>|</tt>). In the extended form, the
+ * resulting output is prefixed with the string literal
+ * <tt>std::ios_base::</tt> indicating the qualfied namespace.
+ *
+ * @subsection rwtest-fmtspec-ext-Io Open Mode \%{Io} \%{\#Io}
+ *
+ * Similar to the <tt>%{Is}</tt> directive except the argument is a
+ * value of the <tt>std::ios_base::openmode</tt> enumeration type and
+ * names in the resulting output correspond to enumerators of this type.
+ *
+ * @subsection rwtest-fmtspec-ext-Iw Seek Direction \%{Iw} \%{\#Iw}
+ *
+ * The argument is a value of type <tt>std::ios_base::seekdir</tt>. In
+ * the plain form, the resulting ouput is formatted as the unqualified
+ * name corresponding to one of the \c seekdir enumerators. In the
+ * extended form, the enumerator is qualified with the enclosing
+ * namespace.
+ *
+ * @subsection rwtest-fmtspec-ext-If Format Flag \%{If} \%{\#Iw}
+ *
+ * Similar to the <tt>%{Is}</tt> directive except the argument is a
+ * value of the <tt>std::ios_base::fmtflags</tt> enumeration type and
+ * names in the resulting output correspond to enumerators of this type.
+ *
+ * @subsection rwtest-fmtspec-ext-Lc Locate Category \%{Lc} \%{\#Lc}
+ *
+ * The argument is an integer type representing a constant defined by
+ * the C <tt><locale.h></tt> header (identified by an <tt>LC_</tt>
+ * prefix) or a <tt>std::locale::category</tt> constant defined by
+ * the C++ <tt><locale></tt> header. The resulting output is
+ * formatted as a character string representing the name of the C or C++
+ * constant enclosed in square brackets (<tt>[</tt>) and <tt>]</tt>).
+ * In the alternate form, the formatted output for C++ constants is
+ * prefixed with the string literal <tt>std::locale::</tt> indicating
+ * the qualified namespace.
+ *
+ * @subsection rwtest-fmtspec-ext-LC Character Classifiers \%{LC} \%{\#LC}
+ *
+ * The argument is an integer type representing enumerators of the
+ * <tt>std::ctype_base::mask</tt> enumeration. The resulting output is
+ * formatted as a character string representing the name of the
+ * enumerator enclosed in square brackets (<tt>[</tt>) and <tt>]</tt>).
+ * In the alternate form, the enumerator is prefixed with the string
+ * literal <tt>std::ctype_base::</tt> indicating the qualified
+ * namespace.
+ *
+ * @subsection rwtest-fmtspec-ext-pid Process Identifier \%{P}
+ *
+ * The argument is a value of the portable \c rw_pid_t type. The
+ * resulting output is formatted as a numeric sequence of digits
+ * representing the corresponding process identifier. The \c P
+ * specifier may be preceded by optional width, justification, and
+ * precision qualifiers.
+ *
+ * @subsection rwtest-fmtspec-ext-str String \%{S}
+ *
+ * The argument is a pointer to an object of the \c std::string class.
+ * If the pointer is null, the resulting output is the string literal
+ * <tt>(null)</tt>. Otherwise, the pointer \c P is converted by calling
+ * the \c P->c_str() function and the result is formatted identical to
+ * the <tt>%s</tt> character string directive.
+ *
+ * @subsection rwtest-fmtspec-ext-tm Time Structure \%{t} \%{\#t}
+ *
+ * The argument is a pointer to a \c tm structure. If the pointer is
+ * null, the resulting output is the string literal \c (null). In the
+ * plain form, the resulting output for a valid pointer is formatted
+ * similar (but not necessarily identical) to the return value of the
+ * \c asctime() function. If the value of any structure member is
+ * outside its valid range, the resulting output is formatting using the
+ * alternate form. In the alternate form, the resulting output is
+ * formatted as a comma-separated sequence of members enclosed in braces
+ * where each member is of the format "name=value [range]". The
+ * "[range]" is only shown if the value is not in the valid range for
+ * the respective member.
+ *
+ */
+
#endif // RW_PRINTF_H_INCLUDED
Re: svn commit: r656686 - in /stdcxx/branches/4.2.x/tests: include/rw_printf.h
src/printf.h
Posted by Martin Sebor <se...@roguewave.com>.
Eric Lemings wrote:
>
>
>> -----Original Message-----
>> From: Martin Sebor [mailto:msebor@gmail.com] On Behalf Of Martin Sebor
>> Sent: Monday, May 19, 2008 4:30 PM
>> To: dev@stdcxx.apache.org
>> Subject: Re: svn commit: r656686 - in
>> /stdcxx/branches/4.2.x/tests: include/rw_printf.h src/printf.h
>>
> ...
>> Alternatively, there could be a separate section for all
>> the directives, independent of any of the "overloads" of
>> rw_printf.
>
> Is there an echo in here? I though I said as much in my previous
> message. :)
You did say something like that but you still haven't explained
what you plan to do about the two sections. I personally don't
have strong preference for where the directives are documented
just as long as they're all in one place.
>
[...]
> Could whip up a script run by cron job that publishes the online
> documentation generated using the doc target from a snapshot of a
> Subversion branch. Wouldn't be hard.
>
> Hypothetical script and usage:
>
> gendocs http://svn.apache.org/viewvc/stdcxx/branches/4.2.x/ \
> http://stdcxx.apache.org/doc/html
Yes. We have three scripts like that already. One for our
current site (including the Class Reference and User Guide),
another for the Forrest prototype of the site, and a third
for the nightly build results. So writing a new one isn't
the most difficult or time-consuming part. Here's what's
involved:
1. Decide on a good location for the generated docs on our
site.
2. Decide whether to generate the docs on people.apache.org
or somewhere else.
2.1 If the former, install Doxygen and any dependencies
on the server (I don't know what they are or if they
are already installed).
2.2 If the latter, decide where and on the method of
delivery (check the generated docs in Subversion
or just scp them into their destination from the
remote server?)
3. Set up a cron job to periodically regenerate the docs
(ideally only after changes to sources).
4. Modify the existing site to link to the new docs.
>
> I'm not sure how the scripts that publish test results work but
> I'm guessing they run locally on the STDCXX web server? In any
> case, the docs and test results would probably be published in
> similar fashion.
Right. I should document it... The script that does this is
~sebor/bin/mkxviews. It works roughly like so:
for each stdcxx source tree st; do
check out $st into $HOME/stdcxx/$st
run $HOME/stdcxx/$st/bin/genxviews
writing results into /www/stdcxx.apache.org/builds/$st
done
I should move the script to /www/stdcxx.apache.org/bin so
that any stdcxx committer can administer it. I should also
modify it so that anyone and everyone can set up their own
cron job to run the script without overwriting anyone else's
results and without doing unnecessary work.
Martin
RE: svn commit: r656686 - in /stdcxx/branches/4.2.x/tests: include/rw_printf.h src/printf.h
Posted by Eric Lemings <Er...@roguewave.com>.
> -----Original Message-----
> From: Martin Sebor [mailto:msebor@gmail.com] On Behalf Of Martin Sebor
> Sent: Monday, May 19, 2008 4:30 PM
> To: dev@stdcxx.apache.org
> Subject: Re: svn commit: r656686 - in
> /stdcxx/branches/4.2.x/tests: include/rw_printf.h src/printf.h
>
...
>
> Alternatively, there could be a separate section for all
> the directives, independent of any of the "overloads" of
> rw_printf.
Is there an echo in here? I though I said as much in my previous
message. :)
> >
> >> 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).
Could whip up a script run by cron job that publishes the online
documentation generated using the doc target from a snapshot of a
Subversion branch. Wouldn't be hard.
Hypothetical script and usage:
gendocs http://svn.apache.org/viewvc/stdcxx/branches/4.2.x/ \
http://stdcxx.apache.org/doc/html
I'm not sure how the scripts that publish test results work but
I'm guessing they run locally on the STDCXX web server? In any
case, the docs and test results would probably be published in
similar fashion.
Brad.
RE: svn commit: r656686 - in /stdcxx/branches/4.2.x/tests: include/rw_printf.h src/printf.h
Posted by Eric Lemings <Er...@roguewave.com>.
> -----Original Message-----
> From: Martin Sebor [mailto:msebor@gmail.com] On Behalf Of Martin Sebor
> Sent: Monday, May 19, 2008 4:30 PM
> To: dev@stdcxx.apache.org
> Subject: Re: svn commit: r656686 - in
> /stdcxx/branches/4.2.x/tests: include/rw_printf.h src/printf.h
>
> Eric Lemings wrote:
> >
> >
> >> -----Original Message-----
> >> From: Martin Sebor [mailto:sebor@roguewave.com]
> >> Sent: Friday, May 16, 2008 11:26 AM
> >> To: dev@stdcxx.apache.org
> >> Subject: Re: svn commit: r656686 - in
> >> /stdcxx/branches/4.2.x/tests: include/rw_printf.h src/printf.h
> >>
...
>
> 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.
Ah, now I see the old comment for the list of formatting directives.
I didn't see it before. I'll remove the old list and incorporate
that into my new doc comments and replace it with a referece to the
new documentation.
Brad.
Re: svn commit: r656686 - in /stdcxx/branches/4.2.x/tests: include/rw_printf.h
src/printf.h
Posted by Martin Sebor <se...@roguewave.com>.
Eric Lemings wrote:
>
>
>> -----Original Message-----
>> From: Martin Sebor [mailto:sebor@roguewave.com]
>> Sent: Friday, May 16, 2008 11:26 AM
>> To: dev@stdcxx.apache.org
>> Subject: Re: svn commit: r656686 - in
>> /stdcxx/branches/4.2.x/tests: include/rw_printf.h src/printf.h
>>
>> elemings@apache.org 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 <er...@roguewave.com>
>>>
>>> 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.
RE: svn commit: r656686 - in /stdcxx/branches/4.2.x/tests: include/rw_printf.h src/printf.h
Posted by Eric Lemings <Er...@roguewave.com>.
> -----Original Message-----
> From: Martin Sebor [mailto:sebor@roguewave.com]
> Sent: Friday, May 16, 2008 11:26 AM
> To: dev@stdcxx.apache.org
> Subject: Re: svn commit: r656686 - in
> /stdcxx/branches/4.2.x/tests: include/rw_printf.h src/printf.h
>
> elemings@apache.org 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 <er...@roguewave.com>
> >
> > 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.
Re: svn commit: r656686 - in /stdcxx/branches/4.2.x/tests: include/rw_printf.h
src/printf.h
Posted by Martin Sebor <se...@roguewave.com>.
elemings@apache.org 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 <er...@roguewave.com>
>
> 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?
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.
Martin
>
>
> Removed:
> stdcxx/branches/4.2.x/tests/src/printf.h
> Modified:
> stdcxx/branches/4.2.x/tests/include/rw_printf.h
>
> Modified: stdcxx/branches/4.2.x/tests/include/rw_printf.h
> URL: http://svn.apache.org/viewvc/stdcxx/branches/4.2.x/tests/include/rw_printf.h?rev=656686&r1=656685&r2=656686&view=diff
> ==============================================================================
> --- stdcxx/branches/4.2.x/tests/include/rw_printf.h (original)
> +++ stdcxx/branches/4.2.x/tests/include/rw_printf.h Thu May 15 07:45:54 2008
> @@ -160,4 +160,186 @@
> rw_asnprintf (char** pbuf, _RWSTD_SIZE_T *pbufsize, const char *fmt, ...);
>
>
> +/**
> + * @page rwtest-fmtspec Formated Output Directives and Conversion Specifiers
> + *
> + * The RWTest library supports all formatted output directives specified
> + * by the C99 standard as well as many other directive extensions. Only
> + * deviations, extensions, and other implmementation-defined behavior are
> + * described below. Consult your system and/or compiler documentation
> + * for specifications of the standard formatting output directives.
> + *
> + * Unless specified otherwise, the following caveats apply to all
> + * directives and conversions. Directives that accept a pointer argument
> + * will convert a null pointer into the string literal <tt>(null)</tt>.
> + *
> + *
> + * @section rwtest-fmtspec-c89 C89 Directives
> + *
> + * @subsection rwtest-fmtspec-c89-ptr Pointer \%p \%\#p
> + *
> + * The argument is a pointer to \c void. The value of the pointer is
> + * converted to a sequence of hexadecimal digits. The number of
> + * converted digits depends on the size of the \c void* type. The
> + * "alternate form" expressed by \c \%\#p immediately precedes converted
> + * digits with a \c 0x prefix.
> + *
> + *
> + * @section rwtest-fmtspec-c99 C99 Directives
> + *
> + * No known deviations or implementation-defined behavior.
> + *
> + *
> + * @section rwtest-fmtspec-ext RWTest Extensions
> + *
> + * @subsection rwtest-fmtspec-ext-bool Boolean \%b
> + *
> + * The argument is a value convertible to \c bool type. If the value
> + * of the argument is nonzero, the value is converted to the string
> + * literal \c true. Otherwise, the value converts to \c false.
> + *
> + * @subsection rwtest-fmtspec-ext-esc-c Escaped Character \%{c} \%{\#c}
> + *
> + * The argument is an integer value converted to <tt>unsigned char</tt>
> + * type. For non-printable characters, the resulting output is formatted
> + * as the corresponding escape sequence. (The value for a horizontal
> + * tab character for example is formatted as the string literal
> + * <tt>\\t</tt> and a zero value may be formatted as the string literal
> + * <tt>\\x00</tt>. In the alternate form, the resulting output is
> + * immediately surrounded with a single quotation mark <tt>'</tt>.
> + *
> + * @subsection rwtest-fmtspec-ext-esc-lc Escaped Wide Character \%{lc} \%{\#lc}
> + *
> + * Similar to the escaped character directive <tt>%{c}</tt> and quoted
> + * escaped character directive <tt>%{\#c}</tt> respectively, except
> + * that the argument is a value of <tt>wchar_t</tt> type.
> + *
> + * @subsection rwtest-fmtspec-ext-s Quoted Character String \%{\#s}
> + *
> + * Similar to the character string directive <tt>%s</tt> except that the
> + * resulting output is surrounded with a double quotation mark <tt>"</tt>.
> + *
> + * @subsection rwtest-fmtspec-ext-ls Quoted Wide Character String \%{\#ls}
> + *
> + * Similar to the quoted character string directive <tt>%{\#s}</tt>
> + * except that the argument is a pointer to a null-terminate sequence of
> + * <tt>wchar_t</tt> type.
> + *
> + * @subsection rwtest-fmtspec-ext-err Error Code \%m \%{\#m}
> + *
> + * The argument is an integer value representing a system-dependent error
> + * code. In the first form, the value is interpreted as an argument of
> + * the \c strerror() function. The formatted result is the return value
> + * of this function using this parameter value. In the second form, the
> + * formatted result is a character sequence representing the
> + * corresponding error name (e.g. \c ENOMEM) if applicable or equivalent
> + * numeric sequence in decimal notation otherwise.
> + *
> + * @subsection rwtest-fmtspec-ext-sig Signal \%K
> + *
> + * The argument is an integer value representing a system-dependent
> + * signal. The resulting output is a character sequence representing
> + * the name of corresponding signal (e.g. \c SIGABRT) if
> + * applicable or equivalent numeric sequence in decimal notation
> + * otherwise.
> + *
> + * @subsection rwtest-fmtspec-ext-bits Bitset \%{b}
> + *
> + * The argument is a pointer to an array of \c char. NOT YET COMPLETE
> + *
> + * @subsection rwtest-fmtspec-ext-Ai Integer Array \%{Ao} \%{Ad} \%{Ax}
> + *
> + * The argument is a pointer to an array of integer type. The resulting
> + * output is formatted as a string of comma-separated integer values.
> + * The notation of each integer value is specified by <tt>o</tt> for
> + * octal, <tt>d</tt> for decimal, or <tt>x</tt> for hexadcimal. An
> + * optional field width specifies the size of elements in the array
> + * (defaults to 1). An optional precision specifies the length of the
> + * array. In the alternate form, the resulting output for octal and
> + * hexidecimal integer values are prefixed with string literals
> + * <tt>0</tt> and <tt>0x</tt> respectively.
> + *
> + * @subsection rwtest-fmtspec-ext-Is Stream State \%{Is} \%{\#Is}
> + *
> + * The argument is a value of type <tt>std::ios_base::iostate</tt>. In
> + * the plain form, the resulting ouput is formatted as a sequence of one
> + * or more unqualified names corresponding to the \c iostate enumerators,
> + * separated by the OR operator (<tt>|</tt>). In the extended form, the
> + * resulting output is prefixed with the string literal
> + * <tt>std::ios_base::</tt> indicating the qualfied namespace.
> + *
> + * @subsection rwtest-fmtspec-ext-Io Open Mode \%{Io} \%{\#Io}
> + *
> + * Similar to the <tt>%{Is}</tt> directive except the argument is a
> + * value of the <tt>std::ios_base::openmode</tt> enumeration type and
> + * names in the resulting output correspond to enumerators of this type.
> + *
> + * @subsection rwtest-fmtspec-ext-Iw Seek Direction \%{Iw} \%{\#Iw}
> + *
> + * The argument is a value of type <tt>std::ios_base::seekdir</tt>. In
> + * the plain form, the resulting ouput is formatted as the unqualified
> + * name corresponding to one of the \c seekdir enumerators. In the
> + * extended form, the enumerator is qualified with the enclosing
> + * namespace.
> + *
> + * @subsection rwtest-fmtspec-ext-If Format Flag \%{If} \%{\#Iw}
> + *
> + * Similar to the <tt>%{Is}</tt> directive except the argument is a
> + * value of the <tt>std::ios_base::fmtflags</tt> enumeration type and
> + * names in the resulting output correspond to enumerators of this type.
> + *
> + * @subsection rwtest-fmtspec-ext-Lc Locate Category \%{Lc} \%{\#Lc}
> + *
> + * The argument is an integer type representing a constant defined by
> + * the C <tt><locale.h></tt> header (identified by an <tt>LC_</tt>
> + * prefix) or a <tt>std::locale::category</tt> constant defined by
> + * the C++ <tt><locale></tt> header. The resulting output is
> + * formatted as a character string representing the name of the C or C++
> + * constant enclosed in square brackets (<tt>[</tt>) and <tt>]</tt>).
> + * In the alternate form, the formatted output for C++ constants is
> + * prefixed with the string literal <tt>std::locale::</tt> indicating
> + * the qualified namespace.
> + *
> + * @subsection rwtest-fmtspec-ext-LC Character Classifiers \%{LC} \%{\#LC}
> + *
> + * The argument is an integer type representing enumerators of the
> + * <tt>std::ctype_base::mask</tt> enumeration. The resulting output is
> + * formatted as a character string representing the name of the
> + * enumerator enclosed in square brackets (<tt>[</tt>) and <tt>]</tt>).
> + * In the alternate form, the enumerator is prefixed with the string
> + * literal <tt>std::ctype_base::</tt> indicating the qualified
> + * namespace.
> + *
> + * @subsection rwtest-fmtspec-ext-pid Process Identifier \%{P}
> + *
> + * The argument is a value of the portable \c rw_pid_t type. The
> + * resulting output is formatted as a numeric sequence of digits
> + * representing the corresponding process identifier. The \c P
> + * specifier may be preceded by optional width, justification, and
> + * precision qualifiers.
> + *
> + * @subsection rwtest-fmtspec-ext-str String \%{S}
> + *
> + * The argument is a pointer to an object of the \c std::string class.
> + * If the pointer is null, the resulting output is the string literal
> + * <tt>(null)</tt>. Otherwise, the pointer \c P is converted by calling
> + * the \c P->c_str() function and the result is formatted identical to
> + * the <tt>%s</tt> character string directive.
> + *
> + * @subsection rwtest-fmtspec-ext-tm Time Structure \%{t} \%{\#t}
> + *
> + * The argument is a pointer to a \c tm structure. If the pointer is
> + * null, the resulting output is the string literal \c (null). In the
> + * plain form, the resulting output for a valid pointer is formatted
> + * similar (but not necessarily identical) to the return value of the
> + * \c asctime() function. If the value of any structure member is
> + * outside its valid range, the resulting output is formatting using the
> + * alternate form. In the alternate form, the resulting output is
> + * formatted as a comma-separated sequence of members enclosed in braces
> + * where each member is of the format "name=value [range]". The
> + * "[range]" is only shown if the value is not in the valid range for
> + * the respective member.
> + *
> + */
> +
> #endif // RW_PRINTF_H_INCLUDED
>
>