[libstdc++] Re: RFC on doxygen & man page style issue

[Phil Edwards <phil at jaj dot com>]

On Tue, Feb 25, 2003 at 01:42:49AM -0500, Phil Edwards wrote:
> The question is whether member
> #1 should additionally appear in the documentation for Derived.

I'm changing this to 'on' for now.  Also, more and better documentation,
concentrating on man pages.


2003-02-25  Phil Edwards  <pme at gcc dot gnu dot org>

	* docs/doxygen/Intro.3:  Update with new (proper) names.
	* docs/doxygen/TODO:  Update.
	* docs/doxygen/run_doxygen:  More comments, fix up man pages.
	Fake entries for standard typedefs.
	* docs/doxygen/user.cfg.in:  Turn INLINE_INHERITED_MEMB back on.
	* docs/html/documentation.html:  Top-level man page is now called
	C++Intro.
	* include/std/std_limits.h:  Doxygenate.


Index: docs/doxygen/Intro.3
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/Intro.3,v
retrieving revision 1.7
diff -u -3 -p -r1.7 Intro.3
--- docs/doxygen/Intro.3	27 Mar 2002 21:41:28 -0000	1.7
+++ docs/doxygen/Intro.3	25 Feb 2003 23:58:45 -0000
@@ -1,8 +1,8 @@
 .\" t
 .\" This man page is released under the FDL as part of libstdc++-v3.
-.TH Intro 3 "27 March 2002" "GNU libstdc++-v3" "Standard C++ Library"
+.TH C++Intro 3 "25 Febuary 2003" "GNU libstdc++-v3" "Standard C++ Library"
 .SH NAME
-Intro \- Introduction to the GNU libstdc++-v3 man pages
+C++Intro \- Introduction to the GNU libstdc++-v3 man pages
 .SH DESCRIPTION
 This man page serves as a brief introduction to the GNU implementation of
 the Standard C++ Library.  For a better introduction and more complete
@@ -12,10 +12,10 @@ homepage listed at the end.
 .P
 All standard library entities are declared within
 .I namespace std
-and have manual entries beginning with "std_".  For example, to see
+and have manual entries beginning with "std::".  For example, to see
 documentation of the template class
 .I std::vector
-one would use "man std_vector".  Some entities do not have a separate man
+one would use "man std::vector".  Some entities do not have a separate man
 page; for those see the main listing in "man Namespace_Std".
 .P
 All the man pages are automatically generated by Doxygen.  For more
@@ -37,7 +37,7 @@ Binder_functors	Functors which "remember
 Comparison_functors	Functors wrapping built-in comparisons.
 Containers	An introduction to container classes.
 Func_ptr_functors	Functors for use with pointers to functions.
-Intro	This page.
+C++Intro	This page.
 Intro_functors	An introduction to function objects, or functors.
 Iterator_types	Programatically distinguishing iterators/pointers.
 Logical_functors	Functors wrapping the Boolean operations.
@@ -112,10 +112,9 @@ need to know about it, but it can be use
 .TP
 .I libstdc++.so[.N]
 The library implementation in shared object form.  This will be used in
-preference to the static archive form by default.  Currently N will either
-start with 3 or with 4, but your system vendor may change the name as they
-see fit.  If N is in the 2.x series, then you are looking at the old
-libstdc++-v2 library, which we do not maintain.
+preference to the static archive form by default.  N will be a number equal
+to or greater than 3.  If N is in the 2.x series, then you are looking at
+the old libstdc++-v2 library, which we do not maintain.
 .TP
 .I libstdc++.la
 .TP
Index: docs/doxygen/TODO
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/TODO,v
retrieving revision 1.10
diff -u -3 -p -r1.10 TODO
--- docs/doxygen/TODO	21 Nov 2002 07:06:40 -0000	1.10
+++ docs/doxygen/TODO	25 Feb 2003 23:58:45 -0000
@@ -19,11 +19,12 @@ entity to the generated TODO page.
 -----------------------------------------------------------
 
 c17             FINISHED (Nothing in Clause 17 "exists" in terms of code.)
-c18             <limits>, Note A
+c18             FINISHED, Note A
 c19             Note A
 c20             Note A
-c21             Untouched, Note B
-c22             Untouched
+c21             Untouched (top-level class note for basic_string done),
+                Note B
+c22             Untouched; see docs/html/22_locale/*
 c23             See doxygroups.cc and Note B.  Notes on what invalidates
                 iterators need to be added.  std::list-specific memfns need
                 to be filled out.
Index: docs/doxygen/run_doxygen
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/run_doxygen,v
retrieving revision 1.19
diff -u -3 -p -r1.19 run_doxygen
--- docs/doxygen/run_doxygen	21 Nov 2002 08:16:32 -0000	1.19
+++ docs/doxygen/run_doxygen	25 Feb 2003 23:58:45 -0000
@@ -1,7 +1,7 @@
 #!/bin/sh
 
 # Runs doxygen and massages the output files.
-# Copyright (C) 2001, 2002 Free Software Foundation, Inc.
+# Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc.
 #
 # Synopsis:  run_doxygen --mode=[user|maint|man]  v3srcdir  v3builddir
 #
@@ -154,6 +154,11 @@ test $do_html = yes && {
       -e "s= at DATE@=${DATEtext}=" \
       ${srcdir}/docs/doxygen/mainpage.html > ${outdir}/html_${mode}/index.html
   cd ${outdir}/html_${mode}
+  # The following bit of line noise changes annoying
+  #   std::foo < typename _Ugly1, typename _Ugly2, .... _DefaultUgly17 >
+  # to user-friendly
+  #   std::foo
+  # in the major "Compound List" page.
   sed -e 's=\(::[[:alnum:]_]*\)&lt; .* &gt;=\1=' annotated.html > annstrip.html
   mv annstrip.html annotated.html
   cp ${srcdir}/docs/doxygen/tables.html tables.html
@@ -231,7 +236,40 @@ a\
     mv TEMP $f
 done
 
-cp ${srcdir}/docs/doxygen/Intro.3 .
+# Also, break this (generated) line up.  It's ugly as sin.
+problematic=`grep -l '[^^]Definition at line' *.3`
+for f in $problematic; do
+    sed 's/Definition at line/\
+.PP\
+&/'  $f > TEMP
+    mv TEMP $f
+done
+
+cp ${srcdir}/docs/doxygen/Intro.3 C++Intro.3
+
+# Why didn't I do this at the start?  Were rabid weasels eating my brain?
+# Who the fsck would "man std_vector" when the class isn't named that?
+for f in std_*; do
+    newname=`echo $f | sed 's/^std_/std::/'`
+    mv $f $newname
+done
+for f in __gnu_cxx_*; do
+    newname=`echo $f | sed 's/^__gnu_cxx_/__gnu_cxx::/'`
+    mv $f $newname
+done
+for f in *__policy_*; do
+    newname=`echo $f | sed 's/__policy_/__policy::/'`
+    mv $f $newname
+done
+
+# Also, for some reason, typedefs don't get their own man pages.  Sigh.
+for f in ios streambuf istream ostream iostream stringbuf \
+         istringstream ostringstream stringstream filebuf ifstream \
+         ofstream fstream string;
+do
+    echo ".so man3/std::basic_${f}.3" > std::${f}.3
+    echo ".so man3/std::basic_${f}.3" > std::w${f}.3
+done
 
 echo ::
 echo :: Man pages in ${outdir}/man
@@ -243,4 +281,3 @@ echo ::
 exit 0
 
 # vim:ts=4:et:
-
Index: docs/doxygen/user.cfg.in
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/user.cfg.in,v
retrieving revision 1.22
diff -u -3 -p -r1.22 user.cfg.in
--- docs/doxygen/user.cfg.in	12 Jan 2003 02:56:49 -0000	1.22
+++ docs/doxygen/user.cfg.in	25 Feb 2003 23:58:46 -0000
@@ -127,7 +127,7 @@ ALWAYS_DETAILED_SEC    = YES
 # ordinary class members. Constructors, destructors and assignment operators of 
 # the base classes will not be shown.
 
-INLINE_INHERITED_MEMB  = NO
+INLINE_INHERITED_MEMB  = YES
 # pedwards -- this is useful, but ch27 gets huge
 
 # If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full 
Index: docs/html/documentation.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/documentation.html,v
retrieving revision 1.28
diff -u -3 -p -r1.28 documentation.html
--- docs/html/documentation.html	4 Feb 2003 17:42:19 -0000	1.28
+++ docs/html/documentation.html	25 Feb 2003 23:58:46 -0000
@@ -84,9 +84,8 @@
    libstdc++-html-*/index.html into a browser.  Feedback (and
    additional documentation!) is welcome.
 </p>
-<p>
- In addition, an initial set of man pages are also available in the
- same place as the HTML collections.  Start with Intro(3).
+<p>In addition, an initial set of man pages are also available in the
+   same place as the HTML collections.  Start with C++Intro(3).
 </p>
 
 
Index: include/std/std_limits.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/std/std_limits.h,v
retrieving revision 1.21
diff -u -3 -p -r1.21 std_limits.h
--- include/std/std_limits.h	30 Jan 2003 07:24:02 -0000	1.21
+++ include/std/std_limits.h	25 Feb 2003 23:58:46 -0000
@@ -149,66 +149,162 @@
 
 namespace std
 {
+  /**
+   *  @brief Describes the rounding style for floating-point types.
+   *
+   *  This is used in the std::numeric_limits class.
+  */
   enum float_round_style
   {
-    round_indeterminate       = -1,
-    round_toward_zero         = 0,
-    round_to_nearest          = 1,
-    round_toward_infinity     = 2,
-    round_toward_neg_infinity = 3
+    round_indeterminate       = -1,    ///< Self-explanatory.
+    round_toward_zero         = 0,     ///< Self-explanatory.
+    round_to_nearest          = 1,     ///< To the nearest representable value.
+    round_toward_infinity     = 2,     ///< Self-explanatory.
+    round_toward_neg_infinity = 3      ///< Self-explanatory.
   };
 
+  /**
+   *  @brief Describes the denormalization for floating-point types.
+   *
+   *  These values represent the presence or absence of a variable number
+   *  of exponent bits.  This type is used in the std::numeric_limits class.
+  */
   enum float_denorm_style
   {
+    /// Indeterminate at compile time whether denormalized values are allowed.
     denorm_indeterminate = -1,
+    /// The type does not allow denormalized values.
     denorm_absent        = 0,
+    /// The type allows denormalized values.
     denorm_present       = 1
   };
 
-  //
-  // The primary class traits
-  //
+  /**
+   *  @brief Part of std::numeric_limits.
+   *
+   *  The @c static @c const members are usable as integral constant
+   *  expressions.
+   *
+   *  @note This is a seperate class for purposes of efficiency; you
+   *        should only access these members as part of an instantiation
+   *        of the std::numeric_limits class.
+  */
   struct __numeric_limits_base
   {
+    /** This will be true for all fundamental types (which have
+        specializations), and false for everything else.  */
     static const bool is_specialized = false;
 
+    /** The number of @c radix digits that be represented without change:  for
+        integer types, the number of non-sign bits in the mantissa; for
+        floating types, the number of @c radix digits in the mantissa.  */
     static const int digits = 0;
+    /** The number of base 10 digits that can be represented without change. */
     static const int digits10 = 0;
+    /** True if the type is signed.  */
     static const bool is_signed = false;
+    /** True if the type is integer.
+     *  @if maint
+     *  Is this supposed to be "if the type is integral"?
+     *  @endif
+    */
     static const bool is_integer = false;
+    /** True if the type uses an exact representation.  "All integer types are
+        exact, but not all exact types are integer.  For example, rational and
+        fixed-exponent representations are exact but not integer."
+        [18.2.1.2]/15  */
     static const bool is_exact = false;
+    /** For integer types, specifies the base of the representation.  For
+        floating types, specifies the base of the exponent representation.  */
     static const int radix = 0;
 
+    /** The minimum negative integer such that @c radix raised to the power of
+        (one less than that integer) is a normalized floating point number.  */
     static const int min_exponent = 0;
+    /** The minimum negative integer such that 10 raised to that power is in
+        the range of normalized floating point numbers.  */
     static const int min_exponent10 = 0;
+    /** The maximum positive integer such that @c radix raised to the power of
+        (one less than that integer) is a representable finite floating point
+	number.  */
     static const int max_exponent = 0;
+    /** The maximum positive integer such that 10 raised to that power is in
+        the range of representable finite floating point numbers.  */
     static const int max_exponent10 = 0;
 
+    /** True if the type has a representation for positive infinity.  */
     static const bool has_infinity = false;
+    /** True if the type has a representation for a quiet (non-signaling)
+        "Not a Number."  */
     static const bool has_quiet_NaN = false;
+    /** True if the type has a representation for a signaling
+        "Not a Number."  */
     static const bool has_signaling_NaN = false;
+    /** See std::float_denorm_style for more information.  */
     static const float_denorm_style has_denorm = denorm_absent;
+    /** "True if loss of accuracy is detected as a denormalization loss,
+        rather than as an inexact result." [18.2.1.2]/42  */
     static const bool has_denorm_loss = false;
 
+    /** True if-and-only-if the type adheres to the IEC 559 standard, also
+        known as IEEE 754.  (Only makes sense for floating point types.)  */
     static const bool is_iec559 = false;
+    /** "True if the set of values representable by the type is finite.   All
+        built-in types are bounded, this member would be false for arbitrary
+	precision types." [18.2.1.2]/54  */
     static const bool is_bounded = false;
+    /** True if the type is @e modulo, that is, if it is possible to add two
+        positive numbers and have a result that wraps around to a third number
+        that is less.  Typically false for floating types, true for unsigned
+        integers, and true for signed integers.  */
     static const bool is_modulo = false;
 
+    /** True if trapping is implemented for this type.  */
     static const bool traps = false;
+    /** True if tinyness is detected before rounding.  (see IEC 559)  */
     static const bool tinyness_before = false;
+    /** See std::float_round_style for more information.  This is only
+        meaningful for floating types; integer types will all be
+	round_toward_zero.  */
     static const float_round_style round_style = round_toward_zero;
   };
 
+  /**
+   *  @brief Properties of fundamental types.
+   *
+   *  This class allows a program to obtain information about the
+   *  representation of a fundamental type on a given platform.  For
+   *  non-fundamental types, the functions will return 0 and the data
+   *  members will all be @c false.
+   *
+   *  @if maint
+   *  _GLIBCPP_RESOLVE_LIB_DEFECTS:  DRs 201 and 184 (hi Gaby!) are
+   *  noted, but not incorporated in this documented (yet).
+   *  @endif
+  */
   template<typename _Tp>
     struct numeric_limits : public __numeric_limits_base
     {
+      /** The minimum finite value, or for floating types with
+          denormalization, the minimum positive normalized value.  */
       static _Tp min() throw() { return static_cast<_Tp>(0); }
+      /** The maximum finite value.  */
       static _Tp max() throw() { return static_cast<_Tp>(0); }
+      /** The @e machine @e epsilon:  the difference between 1 and the least
+          value greater than 1 that is representable.  */
       static _Tp epsilon() throw() { return static_cast<_Tp>(0); }
+      /** The maximum rounding error measurement (see LIA-1).  */
       static _Tp round_error() throw() { return static_cast<_Tp>(0); }
+      /** The representation of positive infinity, if @c has_infinity.  */
       static _Tp infinity() throw()  { return static_cast<_Tp>(0); }
+      /** The representation of a quiet "Not a Number," if @c has_quiet_NaN. */
       static _Tp quiet_NaN() throw() { return static_cast<_Tp>(0); }
+      /** The representation of a signaling "Not a Number," if
+          @c has_signaling_NaN. */
       static _Tp signaling_NaN() throw() { return static_cast<_Tp>(0); }
+      /** The minimum positive denormalized value.  For types where
+          @c has_denorm is false, this is the minimum positive normalized
+	  value.  */
       static _Tp denorm_min() throw() { return static_cast<_Tp>(0); }
     };