Makefile.am (doxygen-maint): The script isn't executable in CVS.

2001-11-23  Phil Edwards  <pme@gcc.gnu.org>

	* Makefile.am (doxygen-maint):  The script isn't executable in CVS.
	* Makefile.in:  Regenerated.
	* docs/doxygen/TODO:  New file listing doxygen work to be done.
	* docs/doxygen/run_doxygen:  Fix up man pages.
	* docs/doxygen/user.cfg.in:  Insert maint-only toggles.
	* docs/doxygen/maint.cfg.in:  Copy from user.cfg and turn toggles on.
	* include/bits/stl_construct.h:  Use new hooks for internal functions.

	* docs/html/17_intro/TODO:  Small updates.
	* docs/html/faq/index.html:  Likewise.
	* docs/html/faq/index.txt:  Regenerated.

	* include/bits/stl_alloc.h:  Doxygenate, reindent comments, remove
	SGI-isms and wrappers.
	(simple_alloc, debug_alloc):  Uglify class names.
	(__default_alloc_template):  Uglify "threads" template parameter and
	update corresponding macros.
	* include/backward/alloc.h:  Bring up to date.

From-SVN: r47296

libstdc++-v3/ChangeLog

+2001-11-23  Phil Edwards  <pme@gcc.gnu.org>
+
+	* Makefile.am (doxygen-maint):  The script isn't executable in CVS.
+	* Makefile.in:  Regenerated.
+	* docs/doxygen/TODO:  New file listing doxygen work to be done.
+	* docs/doxygen/run_doxygen:  Fix up man pages.
+	* docs/doxygen/user.cfg.in:  Insert maint-only toggles.
+	* docs/doxygen/maint.cfg.in:  Copy from user.cfg and turn toggles on.
+	* include/bits/stl_construct.h:  Use new hooks for internal functions.
+
+	* docs/html/17_intro/TODO:  Small updates.
+	* docs/html/faq/index.html:  Likewise.
+	* docs/html/faq/index.txt:  Regenerated.
+
+	* include/bits/stl_alloc.h:  Doxygenate, reindent comments, remove
+	SGI-isms and wrappers.
+	(simple_alloc, debug_alloc):  Uglify class names.
+	(__default_alloc_template):  Uglify "threads" template parameter and
+	update corresponding macros.
+	* include/backward/alloc.h:  Bring up to date.
+
 2001-11-23  Jason Merrill  <jason@redhat.com>
 
 	* src/vterminate.cc (__verbose_terminate_handler): Add leading

libstdc++-v3/Makefile.am

@@ -53,7 +53,8 @@ doxygen:
 doxygen-maint:
 	-(srcdir=`cd ${top_srcdir}; pwd`; \
 	  outdir=`pwd`; \
-	  ${srcdir}/docs/doxygen/run_doxygen --mode=maint $${srcdir} $${outdir})
+	  /bin/sh ${srcdir}/docs/doxygen/run_doxygen \
+	            --mode=maint $${srcdir} $${outdir})
 
 .PHONY: doxygen doxygen-maint
 

libstdc++-v3/Makefile.in

@@ -507,7 +507,8 @@ doxygen:
 doxygen-maint:
 	-(srcdir=`cd ${top_srcdir}; pwd`; \
 	  outdir=`pwd`; \
-	  ${srcdir}/docs/doxygen/run_doxygen --mode=maint $${srcdir} $${outdir})
+	  /bin/sh ${srcdir}/docs/doxygen/run_doxygen \
+	            --mode=maint $${srcdir} $${outdir})
 
 .PHONY: doxygen doxygen-maint
 

libstdc++-v3/docs/doxygen/TODO

+
+The approach I've been using for a given header is to recursively do each
+of the "bits" headers which make up the standard header.  So, e.g., while
+there are five headers making up <algorithm>, three of them were already
+documented in the course of doing other headers.
+
+"Untouched" means I've deliberately skipped it for various reasons, or
+haven't gotten to it yet.  It /will/ be done (by somebody, eventually.)
+
+
+ Area           Still needs to be doxygen-documented
+-----------------------------------------------------------
+
+c17             FINISHED (Nothing in Clause 17 "exists" in terms of code.)
+c18             <limits>, Note A
+c19             Note A
+c20             std_memory.h[20.4], rel_ops (should they be doc'd?), Note A
+c21             Untouched, Note B
+c22             Untouched
+c23             See doxygroups.cc and Note B.
+                stl_alloc.h, stl_uninitialized.h remain from the common files.
+c24             Untouched
+c25             stl_tempbuf.h (small), stl_algo.h (big)
+c26             <complex>, <valarray>, stl_numeric.h[26.4], Note A
+c27             Untouched
+
+backward/       Not scanned by doxygen.  Should it be?
+
+ext/            Untouched
+
+__gnu_cxx       Extensions such as verbose_terminate_handler are documented
+                but do not appear in output, since the __gnu_cxx namespace is
+                itself undocumented.  Should it be?  Eeeeeeehhh...
+
+[1.3.5]         "implementation-defined behavior:  behavior ... that depends
+                on the implementation *and that each implementation shall
+                document*."  [my emphasis]  Not all implementation choices
+                have been thus described; doxygen is not necessarily the
+                appropriate place for such descriptions, either.
+
+-----------------------------------------------------------
+
+NOTES:
+
+A)  So far I have not tried to document any of the <c*> headers.  So entities
+such as atexit() are undocumented throughout the library.
+
+B)  Huge chunks of containers and strings are described in common "Tables"
+in the standard.  How to reproduce this information?
+
+
+vim:ts=4:et:

libstdc++-v3/docs/doxygen/run_doxygen

@@ -4,7 +4,7 @@
 #
 # Synopsis:  run_doxygen --mode=[user|maint]  v3srcdir  v3builddir
 #
-# Originally hacked together by Phil Edwards <pme@sources.redhat.com>
+# Originally hacked together by Phil Edwards <pme@gcc.gnu.org>
 
 
 # We can check now that the version of doxygen is >= this variable.
@@ -162,6 +162,20 @@ for f in $problematic; do
 done
 rm stdheader
 
+# Some of the pages for generated modules have text that confuses certain
+# implementations of man(1), e.g., Linux's.  We need to have another top-level
+# *roff tag to /stop/ the .SH NAME entry.
+#problematic=`egrep --files-without-match '^\.SH SYNOPSIS' [A-Z]*.3`
+problematic='Containers.3 Sequences.3 Assoc_containers.3'
+for f in $problematic; do
+    sed '/^\.SH NAME/{
+n
+a\
+.SH SYNOPSIS
+    }' $f > TEMP
+    mv TEMP $f
+done
+
 cp ${srcdir}/docs/doxygen/Intro.3 .
 
 }

libstdc++-v3/docs/doxygen/user.cfg.in

@@ -50,8 +50,8 @@ OUTPUT_LANGUAGE        = English
 # Private class members and static file members will be hidden unless 
 # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES 
 
-#EXTRACT_ALL            = NO
-EXTRACT_ALL            = YES
+EXTRACT_ALL            = NO
+#EXTRACT_ALL            = YES
 
 # If the EXTRACT_PRIVATE tag is set to YES all private members of a class 
 # will be included in the documentation. 
@@ -125,7 +125,7 @@ INTERNAL_DOCS          = NO
 CLASS_DIAGRAMS         = YES
 
 # If the SOURCE_BROWSER tag is set to YES then a list of source files will 
-# be generated. Documented entities will be cross-referenced with these sources. 
+# be generated. Documented entities will be cross-referenced with these sources.
 
 SOURCE_BROWSER         = YES
 
@@ -234,7 +234,8 @@ GENERATE_BUGLIST       = YES
 # will result in a user defined paragraph with heading "Side Effects:". 
 # You can put \n's in the value part of an alias to insert newlines. 
 
-ALIASES                = 
+ALIASES                = "maint=\if maint" \
+                         "endmaint=\endif"
 
 # The MAX_INITIALIZER_LINES tag determines the maximum number of lines 
 # the initial value of a variable or define consist of for it to appear in 

libstdc++-v3/docs/html/17_intro/TODO

@@ -152,8 +152,6 @@ sources, with macro-guards.
 
 - write filebuf for wide characters
 
-- replace stl/bits/stl_config 
-
 - add feature-test macros for non-standard extensions
 
 - move major extensions into separate namespace (e.g. stl::)
@@ -166,8 +164,6 @@ sources, with macro-guards.
   facets, and construct them lazily so unused facets need not be constructed 
   when the locale is. 
 
-- get mknumeric_limits coope with 'exotic' OSes.
-
 - <cmath>: provide missing names. 
 
 - provide testsuites for numerics.

libstdc++-v3/docs/html/faq/index.html

@@ -99,7 +99,7 @@ http://gcc.gnu.org/onlinedocs/libstdc++/faq/</a>.</p>
 <h1><a name="1_0">1.0 General Information</a></h1>
 <!-- I suspect these will mostly be links to/into existing documents. -->
    <h2><a name="1_1">1.1 What is libstdc++-v3?</a></h2>
-      <p>The GNU Standard C++ Library v3, or libstdc++-2.9x, is an 
+      <p>The GNU Standard C++ Library v3 is an
          ongoing project to implement the ISO 14882 Standard C++ library 
          as described in chapters 17 through 27 and annex D.  As the 
          library reaches stable plateaus, it is captured in a snapshot
@@ -109,10 +109,15 @@ http://gcc.gnu.org/onlinedocs/libstdc++/faq/</a>.</p>
          far the project has come, or just want the latest
          bleeding-edge code, the up-to-date source is available over
          anonymous CVS, and can even be browsed over the Web (see below). 
-      </p> 
+      </p>
+      <p>The older libstdc++-v2 project is no longer maintained; the code
+         has been completely replaced and rewritten.
+         <a href="#4_4_interface">If you are using V2</a>, then you need to
+         report bugs to your system vendor, not to the V3 list.
+      </p>
       <p>A more formal description of the V3 goals can be found in the
          official <a href="../17_intro/DESIGN">design document</a>. 
-      </p> 
+      </p>
 
 <hr>
    <h2><a name="1_2">1.2 Why should I use libstdc++?</a></h2>
@@ -582,8 +587,10 @@ New:
            do anyhow; see the last paragraph of the page describing
          <a href="http://gcc.gnu.org/gnatswrite.html">the GCC bug database</a>).
         </p>
-        <p>If the headers are in <CODE>${prefix}/include/g++-3</CODE>, then
-           you are using the old libstdc++-v2 library, which is nonstandard
+        <p>If the headers are in <code>${prefix}/include/g++-3</code>, or if
+           the installed library's name looks like <code>libstdc++-2.10.a</code>
+           or <code>libstdc++-libc6-2.10.so</code>,
+           then you are using the old libstdc++-v2 library, which is nonstandard
            and unmaintained.  Do not report problems with -v2 to the -v3
            mailing list.
         </p>

libstdc++-v3/include/backward/alloc.h

@@ -48,8 +48,8 @@
 #include <bits/stl_alloc.h>
 
 using std::__malloc_alloc_template; 
-using std::simple_alloc; 
-using std::debug_alloc; 
+using std::__simple_alloc; 
+using std::__debug_alloc; 
 using std::alloc; 
 using std::single_client_alloc; 
 using std::allocator;

libstdc++-v3/include/bits/stl_construct.h

@@ -67,10 +67,10 @@
 namespace std
 {
   /**
-   * Invoke an allocated object's constructor with an initializer.
-   *
-   * This function is not part of the C++ standard but is used internally
-   * within the library.
+   * @maint
+   * Constructs an object in existing memory by invoking an allocated
+   * object's constructor with an initializer.
+   * @endmaint
    */
   template <class _T1, class _T2>
     inline void
@@ -78,10 +78,10 @@ namespace std
     { new (static_cast<void*>(__p)) _T1(__value); }
   
   /**
-   * Invoke an allocated object's constructor without an initializer.
-   *
-   * This function is not part of the C++ standard but is used internally
-   * within the library.
+   * @maint
+   * Constructs an object in existing memory by invoking an allocated
+   * object's default constructor (no initializers).
+   * @endmaint
    */
   template <class _T1>
     inline void
@@ -89,9 +89,11 @@ namespace std
     { new (static_cast<void*>(__p)) _T1(); }
 
   /**
+   * @maint
    * Destroy a range of objects with nontrivial destructors.  
    *
    * This is a helper function used only by _Destroy().
+   * @endmaint
    */
   template <class _ForwardIterator>
     inline void
@@ -99,11 +101,13 @@ namespace std
     { for ( ; __first != __last; ++__first) _Destroy(&*__first); }
 
   /**
+   * @maint
    * Destroy a range of objects with trivial destructors.  Since the destructors
    * are trivial, there's nothing to do and hopefully this function will be
    * entirely optimized away.
    *
    * This is a helper function used only by _Destroy().
+   * @endmaint
    */
   template <class _ForwardIterator> 
     inline void
@@ -111,10 +115,9 @@ namespace std
     { }
 
   /**
+   * @maint
    * Destroy the object pointed to by a pointer type.
-   *
-   * This function is not part of the C++ standard but is used internally
-   * within the library.
+   * @endmaint
    */
   template <class _Tp>
     inline void
@@ -122,12 +125,11 @@ namespace std
     { __pointer->~_Tp(); }
   
   /**
+   * @maint
    * Destroy a range of objects.  If the value_type of the object has
    * a trivial destructor, the compiler should optimize all of this
    * away, otherwise the objects' destructors must be invoked.
-   *
-   * This function is not part of the C++ standard but is used internally
-   * within the library.
+   * @endmaint
    */
   template <class _ForwardIterator>
     inline void