[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?
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
