2002-01-28 Phil Edwards <pme@gcc.gnu.org>

	* Makefile.am (doxygen, doxygen-maint, doxygen-man):  Tweak targets.
	* Makefile.in:  Regenerate.

	* docs/doxygen/run_doxygen:  Update, mostly for man pages.
	* docs/doxygen/Intro.3:  Update.
	* docs/doxygen/TODO:  Update.
	* docs/doxygen/doxygroups.cc:  Add namespace hook for __gnu_cxx.
	* docs/doxygen/mainpage.doxy:  Update.
	* docs/doxygen/user.cfg.in:  Update for header rename.  Also
	regenerate comments and variables with 1.2.12.
	* docs/doxygen/maint.cfg.in:  Remove file.

	* include/bits/stl_relops.h:  Doxygenate.
	* include/bits/stl_tempbuf.h (std::_Temporary_buffer):  Likewise.

	* include/c_std/std_cassert.h, include/c_std/std_cctype.h,
	include/c_std/std_cerrno.h, include/c_std/std_cfloat.h,
	include/c_std/std_ciso646.h, include/c_std/std_climits.h,
	include/c_std/std_clocale.h, include/c_std/std_cmath.h,
	include/c_std/std_csetjmp.h, include/c_std/std_csignal.h,
	include/c_std/std_cstdarg.h, include/c_std/std_cstddef.h,
	include/c_std/std_cstdio.h, include/c_std/std_cstdlib.h,
	include/c_std/std_cstring.h, include/c_std/std_ctime.h,
	include/c_std/std_cwchar.h, include/c_std/std_cwctype.h,
	include/ext/algorithm, include/ext/functional, include/ext/hash_map,
	include/ext/hash_set, include/ext/iterator, include/ext/memory,
	include/ext/numeric, include/ext/rb_tree, include/ext/rope,
	include/ext/ropeimpl.h, include/ext/slist, include/ext/stl_hash_fun.h,
	include/ext/stl_hashtable.h, include/ext/stl_rope.h,
	include/std/std_algorithm.h, include/std/std_bitset.h,
	include/std/std_complex.h, include/std/std_deque.h,
	include/std/std_fstream.h, include/std/std_functional.h,
	include/std/std_iomanip.h, include/std/std_ios.h,
	include/std/std_iosfwd.h, include/std/std_iostream.h,
	include/std/std_istream.h, include/std/std_iterator.h,
	include/std/std_limits.h, include/std/std_list.h,
	include/std/std_locale.h, include/std/std_map.h,
	include/std/std_memory.h, include/std/std_numeric.h,
	include/std/std_ostream.h, include/std/std_queue.h,
	include/std/std_set.h, include/std/std_sstream.h,
	include/std/std_stack.h, include/std/std_stdexcept.h,
	include/std/std_streambuf.h, include/std/std_string.h,
	include/std/std_utility.h, include/std/std_valarray.h,
	include/std/std_vector.h:  Add/correct @file doxygen hook.

	* include/ext/memory:  Doxygenate most of rest of file.
	* libsupc++/exception:  Doxygen output formatting.
	* libsupc++/new:  Say which header it is.

	* testsuite/lib/libstdc++-v3-dg.exp:  Fix spacing.
	* docs/html/19_diagnostics/howto.html:  Describe concept-checks switch.
	* docs/html/23_containers/howto.html:  Describe O(n) list::size().
	* docs/html/27_io/howto.html:  Also link to Langer and Kreft text.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@49300 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 26 insertions, 2 deletions

diff --git a/libstdc++-v3/include/ext/memory b/libstdc++-v3/include/ext/memory
index 3318611f048..5626b70e6af 100644
--- a/libstdc++-v3/include/ext/memory
+++ b/libstdc++-v3/include/ext/memory
@@ -53,6 +53,12 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file ext/memory
+ *  This file is a GNU extension to the Standard C++ Library (possibly
+ *  containing extensions from the HP/SGI STL subset).  You should only
+ *  include this header if you are using GCC 3 or later.
+ */
+
 #ifndef _EXT_MEMORY
 #define _EXT_MEMORY
 
@@ -67,7 +73,6 @@ namespace __gnu_cxx
   using std::__iterator_category;
   using std::_Temporary_buffer;
   
-  // uninitialized_copy_n (not part of the C++ standard)
 
   template<typename _InputIter, typename _Size, typename _ForwardIter>
     pair<_InputIter, _ForwardIter>
@@ -114,6 +119,7 @@ namespace __gnu_cxx
    *  @param  last   An input iterator.
    *  @param  result An output iterator.
    *  @return   result + (first - last)
+   *  @ingroup SGIextensions
    *
    *  Like copy(), but does not require an initialized output range.
   */
@@ -127,7 +133,23 @@ namespace __gnu_cxx
 
 
   /**
-   *  Must come back and figure out these notes.
+   *  This class provides similar behavior and semantics of the standard
+   *  functions get_temporary_buffer() and return_temporary_buffer(), but
+   *  encapsulated in a type vaguely resembling a standard container.
+   *
+   *  By default, a temporary_buffer<Iter> stores space for objects of
+   *  whatever type the Iter iterator points to.  It is constructed from a
+   *  typical [first,last) range, and provides the begin(), end(), size()
+   *  functions, as well as requested_size().  For non-trivial types, copies
+   *  of *first will be used to initialize the storage.
+   *
+   *  @c malloc is used to obtain underlying storage.
+   *
+   *  Like get_temporary_buffer(), not all the requested memory may be
+   *  available.  Ideally, the created buffer will be large enough to hold a
+   *  copy of [first,last), but if size() is less than requested_size(),
+   *  then this didn't happen.
+   *
    *  @ingroup SGIextensions
   */
   template <class _ForwardIterator, 
@@ -135,8 +157,10 @@ namespace __gnu_cxx
 	      = typename std::iterator_traits<_ForwardIterator>::value_type >
   struct temporary_buffer : public _Temporary_buffer<_ForwardIterator, _Tp>
   {
+    /// Requests storage large enough to hold a copy of [first,last).
     temporary_buffer(_ForwardIterator __first, _ForwardIterator __last)
       : _Temporary_buffer<_ForwardIterator, _Tp>(__first, __last) {}
+    /// Destroys objects and frees storage.
     ~temporary_buffer() {}
   };