2001-07-11 Phil Edwards <pme@sources.redhat.com>

	* docs/doxygen/run_doxygen:  Don't keep output from previous run.
	* docs/doxygen/user.cfg.in:  Tweaks.
	* include/bits/c++config:  Documentation comments for Doxygen.
	* include/bits/char_traits.h:  Likewise.
	* include/bits/limits_generic.h:  Likewise.
	* include/bits/std_stdexcept.h:  Likewise.
	* include/bits/stl_pair.h:  Likewise.
	* libsupc++/exception:  Likewise.
	* libsupc++/new:  Likewise.
	* libsupc++/typeinfo:  Likewise.
	* libmath/Makefile.am:  Update and correct copyright.


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

1 files changed, 23 insertions, 1 deletions

diff --git a/libstdc++-v3/libsupc++/new b/libstdc++-v3/libsupc++/new
index 56cc1833fe8..0d1810c6207 100644
--- a/libstdc++-v3/libsupc++/new
+++ b/libstdc++-v3/libsupc++/new
@@ -28,6 +28,12 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file new
+ *  This header defines several functions to manage dynamic memory and
+ *  handling memory allocation errors; see
+ *  http://gcc.gnu.org/onlinedocs/libstdc++/18_support/howto.html#4 for more.
+ */
+
 #ifndef __NEW__
 #define __NEW__
 
@@ -38,6 +44,8 @@ extern "C++" {
 
 namespace std 
 {
+  /** @c bad_alloc (or classes derived from it) is used to report allocation
+   *  errors from the throwing forms of @c new.  */
   class bad_alloc : public exception 
   {
   public:
@@ -47,11 +55,24 @@ namespace std
 
   struct nothrow_t { };
   extern const nothrow_t nothrow;
+  /** If you write your own error handler to be called by @c new, it must
+   *  be of this type.  */
   typedef void (*new_handler)();
+  /// Takes a replacement handler as the argument, returns the previous handler.
   new_handler set_new_handler(new_handler);
 } // namespace std
 
-// Replaceable signatures.
+//@{
+/** These are replaceable signatures:
+ *  - normal single new and delete (no arguments, throw @c bad_alloc on error)
+ *  - normal array new and delete (same)
+ *  - @c nothrow single new and delete (take a @c nothrow argument, return
+ *    @c NULL on error)
+ *  - @c nothrow array new and delete (same)
+ *
+ *  Placement new and delete signatures (take a memory address argument,
+ *  does nothing) may not be replaced by a user's program.
+*/
 void *operator new(std::size_t) throw (std::bad_alloc);
 void *operator new[](std::size_t) throw (std::bad_alloc);
 void operator delete(void *) throw();
@@ -64,6 +85,7 @@ void operator delete[](void *, const std::nothrow_t&) throw();
 // Default placement versions of operator new.
 inline void *operator new(std::size_t, void *place) throw() { return place; }
 inline void *operator new[](std::size_t, void *place) throw() { return place; }
+//@}
 } // extern "C++"
 
 #endif