From 669f7a035a384894ac482e00c291d393a21ba2d0 Mon Sep 17 00:00:00 2001 From: Phil Edwards Date: Wed, 11 Jul 2001 19:35:49 +0000 Subject: [PATCH] run_doxygen: Don't keep output from previous run. 2001-07-11 Phil Edwards * 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. From-SVN: r43948 --- libstdc++-v3/ChangeLog | 14 +++++++++ libstdc++-v3/docs/doxygen/run_doxygen | 8 ++++-- libstdc++-v3/docs/doxygen/user.cfg.in | 19 +++++++++++-- libstdc++-v3/include/bits/c++config | 4 +++ libstdc++-v3/include/bits/char_traits.h | 8 +++--- libstdc++-v3/include/bits/limits_generic.h | 14 +++++++++ libstdc++-v3/include/bits/std_stdexcept.h | 33 ++++++++++++++++++++++ libstdc++-v3/include/bits/stl_pair.h | 33 ++++++++++++++++++---- libstdc++-v3/libmath/Makefile.am | 2 +- libstdc++-v3/libsupc++/exception | 33 ++++++++++++++++++++++ libstdc++-v3/libsupc++/new | 24 +++++++++++++++- libstdc++-v3/libsupc++/typeinfo | 24 ++++++++++++---- 12 files changed, 194 insertions(+), 22 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index ece858ceefd..15e0bc64372 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,17 @@ +2001-07-11 Phil Edwards + + * 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. + 2001-07-10 Gabriel Dos Reis * acinclude.m4: Don't AC_REPLACE_MATHFUNCS expf and atan2f. diff --git a/libstdc++-v3/docs/doxygen/run_doxygen b/libstdc++-v3/docs/doxygen/run_doxygen index b329a1304d2..8af7be37c76 100644 --- a/libstdc++-v3/docs/doxygen/run_doxygen +++ b/libstdc++-v3/docs/doxygen/run_doxygen @@ -5,7 +5,7 @@ # Synopsis: run_doxygen --mode=[user|maint] v3srcdir v3builddir # # Originally hacked together by Phil Edwards -# $Id: run_doxygen,v 1.4 2001/04/29 01:40:34 pme Exp $ +# $Id: run_doxygen,v 1.5 2001/06/11 13:04:07 pme Exp $ # We can check now that the version of doxygen is >= this variable. @@ -75,7 +75,7 @@ parse_options() { blank= Id=is echo You expect this dinky script to track a version? Okay, here - echo it $Id: run_doxygen,v 1.4 2001/04/29 01:40:34 pme Exp $blank + echo it $Id: run_doxygen,v 1.5 2001/06/11 13:04:07 pme Exp $blank exit 0 ;; *) @@ -115,7 +115,9 @@ case x"$mode" in exit 1 ;; esac -test -d $outdir || (mkdir -p $outdir ; chmod u+w $outdir) +rm -rf $outdir +mkdir -p $outdir +chmod u+w $outdir ( set -e cd $srcdir diff --git a/libstdc++-v3/docs/doxygen/user.cfg.in b/libstdc++-v3/docs/doxygen/user.cfg.in index eae5c69016c..97c0ca4fcc0 100644 --- a/libstdc++-v3/docs/doxygen/user.cfg.in +++ b/libstdc++-v3/docs/doxygen/user.cfg.in @@ -197,7 +197,7 @@ SORT_MEMBER_DOCS = YES # member in the group (if any) for the other members of the group. By default # all members of a group must be documented explicitly. -DISTRIBUTE_GROUP_DOC = NO +DISTRIBUTE_GROUP_DOC = YES # The TAB_SIZE tag can be used to set the number of spaces in a tab. # Doxygen uses this value to replace tabs by spaces in code fragments. @@ -305,7 +305,22 @@ WARN_LOGFILE = INPUT = docs/doxygen \ libsupc++ \ include \ - src + src \ +libsupc++/exception libsupc++/new libsupc++/typeinfo include/ext/hash_map \ +include/ext/hash_set include/ext/rope include/ext/slist include/std/algorithm \ +include/std/bitset include/std/cassert include/std/cctype \ +include/std/cerrno include/std/cfloat include/std/ciso646 include/std/climits \ +include/std/clocale include/std/cmath include/std/complex include/std/csetjmp \ +include/std/csignal include/std/cstdarg include/std/cstddef \ +include/std/cstdio include/std/cstdlib include/std/cstring \ +include/std/ctime include/std/cwchar include/std/cwctype include/std/deque \ +include/std/fstream include/std/functional include/std/iomanip \ +include/std/ios include/std/iosfwd include/std/iostream include/std/istream \ +include/std/iterator include/std/limits include/std/list include/std/locale \ +include/std/map include/std/memory include/std/numeric include/std/ostream \ +include/std/queue include/std/set include/std/sstream include/std/stack \ +include/std/stdexcept include/std/streambuf include/std/string \ +include/std/utility include/std/valarray include/std/vector # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp diff --git a/libstdc++-v3/include/bits/c++config b/libstdc++-v3/include/bits/c++config index 4c46391af44..abf3f8eb7af 100644 --- a/libstdc++-v3/include/bits/c++config +++ b/libstdc++-v3/include/bits/c++config @@ -109,4 +109,8 @@ // should be cleaned up. # define __stl_assert(expr) +/** @namespace std + * @brief Everything defined by the ISO C++ Standard is within namespace std. + */ + // End of prewritten config; the discovered settings follow. diff --git a/libstdc++-v3/include/bits/char_traits.h b/libstdc++-v3/include/bits/char_traits.h index eb3f9fec3a2..a468bed90af 100644 --- a/libstdc++-v3/include/bits/char_traits.h +++ b/libstdc++-v3/include/bits/char_traits.h @@ -41,9 +41,9 @@ namespace std { - // 21.1.2 Basis for explicit _Traits specialization - // NB: That for any given actual character type this definition is - // probably wrong. + /// 21.1.2 Basis for explicit _Traits specialization + /// NB: That for any given actual character type this definition is + /// probably wrong. template struct char_traits { @@ -127,7 +127,7 @@ namespace std }; - // 21.1.4 char_traits specializations + /// 21.1.4 char_traits specializations template<> struct char_traits { diff --git a/libstdc++-v3/include/bits/limits_generic.h b/libstdc++-v3/include/bits/limits_generic.h index 8ad003340b0..42cae71a770 100644 --- a/libstdc++-v3/include/bits/limits_generic.h +++ b/libstdc++-v3/include/bits/limits_generic.h @@ -35,6 +35,11 @@ // 18.2.1 // +/** @file limits_generic.h + * ISO 14882:1998 + * 18.2.1 + */ + #ifndef _CPP_NUMERIC_LIMITS #define _CPP_NUMERIC_LIMITS 1 @@ -49,6 +54,7 @@ namespace std { + /// Rounding style determines the behavior of floating-point calculations. enum float_round_style { round_indeterminate = -1, round_toward_zero = 0, @@ -57,12 +63,20 @@ namespace std { round_toward_neg_infinity = 3 }; + /// This enum signals whether a type has denormalization. enum float_denorm_style { denorm_indeterminate = -1, denorm_absent = 0, denorm_present = 1 }; + /** + * [18.2.1]/1: "The numeric_limits component provides a C++ program + * with information about various properties of the implementation's + * representation of the fundamental types." All of the standard + * fundamental types have specializations of this class template. + * @brief Properties of fundamental types on a per-platform basis. + */ template struct numeric_limits { static const bool is_specialized = false; diff --git a/libstdc++-v3/include/bits/std_stdexcept.h b/libstdc++-v3/include/bits/std_stdexcept.h index ee9ebf19449..66bac5011be 100644 --- a/libstdc++-v3/include/bits/std_stdexcept.h +++ b/libstdc++-v3/include/bits/std_stdexcept.h @@ -31,6 +31,13 @@ // ISO C++ 19.1 Exception classes // +/** @file std_stdexcept.h + * The Standard C++ library provides classes to be used to report certain + * errors (17.4.4.8) in C++ programs. In the error model reflected in these + * classes, errors are divided into two broad categories: logic errors and + * runtime errors. + */ + #ifndef _CPP_STDEXCEPT #define _CPP_STDEXCEPT 1 @@ -41,72 +48,98 @@ namespace std { + /** Logic errors represent problems in the internal logic of a program; + * in theory, these are preventable, and even detectable before the + * program runs (e.g., violations of class invariants). + * @brief One of two subclasses of exception. + */ class logic_error : public exception { string _M_msg; public: + /** Takes a character string describing the error. */ explicit logic_error(const string& __arg); virtual ~logic_error() throw(); + /** Returns a C-style character string describing the general cause of + * the current error (the same string passed to the ctor). */ virtual const char* what() const throw(); }; + /** Thrown by the library, or by you, to report domain errors (domain in + * the mathmatical sense). */ class domain_error : public logic_error { public: explicit domain_error(const string& __arg); }; + /** Thrown to report invalid arguments to functions. */ class invalid_argument : public logic_error { public: explicit invalid_argument(const string& __arg); }; + /** Thrown when an object is constructed that would exceed its maximum + * permitted size (e.g., a basic_string instance). */ class length_error : public logic_error { public: explicit length_error(const string& __arg); }; + /** This represents an argument whose value is not within the expected + * range (e.g., boundary checks in basic_string). */ class out_of_range : public logic_error { public: explicit out_of_range(const string& __arg); }; + /** Runtime errors represent problems outside the scope of a program; + * they cannot be easily predicted and can generally only be caught as + * the program executes. + * @brief One of two subclasses of exception. + */ class runtime_error : public exception { string _M_msg; public: + /** Takes a character string describing the error. */ explicit runtime_error(const string& __arg); virtual ~runtime_error() throw(); + /** Returns a C-style character string describing the general cause of + * the current error (the same string passed to the ctor). */ virtual const char* what() const throw(); }; + /** Thrown to indicate range errors in internal computations. */ class range_error : public runtime_error { public: explicit range_error(const string& __arg); }; + /** Thrown to indicate arithmetic overflow. */ class overflow_error : public runtime_error { public: explicit overflow_error(const string& __arg); }; + /** Thrown to indicate arithmetic underflow. */ class underflow_error : public runtime_error { public: diff --git a/libstdc++-v3/include/bits/stl_pair.h b/libstdc++-v3/include/bits/stl_pair.h index 27bc50d39a6..b10f96545f4 100644 --- a/libstdc++-v3/include/bits/stl_pair.h +++ b/libstdc++-v3/include/bits/stl_pair.h @@ -53,8 +53,9 @@ * purpose. It is provided "as is" without express or implied warranty. */ -/* NOTE: This is an internal header file, included by other STL headers. - * You should not attempt to use it directly. +/** @file stl_pair.h + * This is an internal header file, included by other STL headers. You + * should not attempt to use it directly. */ #ifndef __SGI_STL_INTERNAL_PAIR_H @@ -63,31 +64,38 @@ namespace std { +/// pair holds two objects of arbitrary type. template struct pair { - typedef _T1 first_type; - typedef _T2 second_type; + typedef _T1 first_type; ///< @c first_type is the first bound type + typedef _T2 second_type; ///< @c second_type is the second bound type - _T1 first; - _T2 second; + _T1 first; ///< @c first is a copy of the first object + _T2 second; ///< @c second is a copy of the second object #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS //265. std::pair::pair() effects overly restrictive + /** The default constructor creates @c first and @c second using their + * respective default constructors. */ pair() : first(), second() {} #else pair() : first(_T1()), second(_T2()) {} #endif + /** Two objects may be passed to a @c pair constructor to be copied. */ pair(const _T1& __a, const _T2& __b) : first(__a), second(__b) {} + /** There is also a templated copy ctor for the @c pair class itself. */ template pair(const pair<_U1, _U2>& __p) : first(__p.first), second(__p.second) {} }; +/// Two pairs of the same type are equal iff their members are equal. template inline bool operator==(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) { return __x.first == __y.first && __x.second == __y.second; } +/// ...put link to onlinedocs here... template inline bool operator<(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) { @@ -95,26 +103,39 @@ inline bool operator<(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) (!(__y.first < __x.first) && __x.second < __y.second); } +/// Uses @c operator== to find the result. template inline bool operator!=(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) { return !(__x == __y); } +/// Uses @c operator< to find the result. template inline bool operator>(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) { return __y < __x; } +/// Uses @c operator< to find the result. template inline bool operator<=(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) { return !(__y < __x); } +/// Uses @c operator< to find the result. template inline bool operator>=(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) { return !(__x < __y); } +/** + * @brief A convenience wrapper for creating a pair from two objects. + * @param x The first object. + * @param y The second object. + * @return A newly-constructed pair<> object of the appropriate type. + * + * The standard requires that the objects be passed by reference-to-const, + * but LWG issue #181 says they should be passed by const value. + */ template #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS //181. make_pair() unintended behavior diff --git a/libstdc++-v3/libmath/Makefile.am b/libstdc++-v3/libmath/Makefile.am index e3404fcaadf..951695a6830 100644 --- a/libstdc++-v3/libmath/Makefile.am +++ b/libstdc++-v3/libmath/Makefile.am @@ -1,6 +1,6 @@ ## Makefile for the math subdirectory of the GNU C++ Standard library. ## -## Copyright (C) 1997, 1998, 1999, 2000 Cygnus Solutions +## Copyright (C) 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc. ## ## This file is part of the libstdc++ version 3 distribution. ## Process this file with automake to produce Makefile.in. diff --git a/libstdc++-v3/libsupc++/exception b/libstdc++-v3/libsupc++/exception index 3676a731481..a1daf8811cc 100644 --- a/libstdc++-v3/libsupc++/exception +++ b/libstdc++-v3/libsupc++/exception @@ -28,6 +28,11 @@ // invalidate any other reasons why the executable file might be covered by // the GNU General Public License. +/** @file exception + * This header defines several types and functions relating to the + * handling of exceptions in a C++ program. + */ + #ifndef __EXCEPTION__ #define __EXCEPTION__ @@ -35,14 +40,24 @@ extern "C++" { namespace std { + /** This is the base class for all exceptions thrown by the standard + * library, and by certain language expressions. You are free to derive + * your own %exception classes, or use a different hierarchy, or to + * throw non-class data (e.g., fundamental types). + * @brief Base class for all library exceptions. + */ class exception { public: exception() throw() { } virtual ~exception() throw(); + /** Returns a C-style character string describing the general cause + * of the current error. */ virtual const char* what() const throw(); }; + /** If an %exception is thrown which is not listed in a function's + * %exception specification, one of these may be thrown. */ class bad_exception : public exception { public: @@ -50,15 +65,33 @@ namespace std virtual ~bad_exception() throw(); }; + /// If you write a replacement %terminate handler, it must be of this type. typedef void (*terminate_handler) (); + /// If you write a replacement %unexpected handler, it must be of this type. typedef void (*unexpected_handler) (); + /// Takes a new handler function as an argument, returns the old function. terminate_handler set_terminate(terminate_handler) throw(); + /** The runtime will call this function if %exception handling must be + * abandoned for any reason. */ void terminate() __attribute__ ((__noreturn__)); + /// Takes a new handler function as an argument, returns the old function. unexpected_handler set_unexpected(unexpected_handler) throw(); + /** The runtime will call this function if an %exception is thrown which + * violates the function's %exception specification. */ void unexpected() __attribute__ ((__noreturn__)); + /** [18.6.4]/1: "Returns true after completing evaluation of a + * throw-expression until either completing initialization of the + * exception-declaration in the matching handler or entering @c unexpected() + * due to the throw; or after entering @c terminate() for any reason + * other than an explicit call to @c terminate(). [Note: This includes + * stack unwinding [15.2]. end note]" + * + * 2: "When @c uncaught_exception() is true, throwing an %exception can + * result in a call of @c terminate() (15.5.1)." + */ bool uncaught_exception() throw(); } // namespace std 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 diff --git a/libstdc++-v3/libsupc++/typeinfo b/libstdc++-v3/libsupc++/typeinfo index 8d8133b6a5c..6cabf7508eb 100644 --- a/libstdc++-v3/libsupc++/typeinfo +++ b/libstdc++-v3/libsupc++/typeinfo @@ -27,6 +27,10 @@ // invalidate any other reasons why the executable file might be covered by // the GNU General Public License. +/** @file typeinfo + * This header provides RTTI support. + */ + #ifndef __TYPEINFO__ #define __TYPEINFO__ @@ -49,17 +53,20 @@ namespace __cxxabiv1 namespace std { + /** The @c type_info class describes type information generated by + * an implementation. + * @brief Used in RTTI. */ class type_info { public: - // Destructor. Being the first non-inline virtual function, this - // controls in which translation unit the vtable is emitted. The - // compiler makes use of that information to know where to emit - // the runtime-mandated type_info structures in the new-abi. + /** Destructor. Being the first non-inline virtual function, this + * controls in which translation unit the vtable is emitted. The + * compiler makes use of that information to know where to emit + * the runtime-mandated type_info structures in the new-abi. */ virtual ~type_info(); private: - // Assigning type_info is not supported. made private. + /// Assigning type_info is not supported. Made private. type_info& operator=(const type_info&); type_info(const type_info&); @@ -71,6 +78,8 @@ namespace std public: // the public interface + /** Returns an \e implementation-defined byte string; this is not + * portable between compilers! */ const char* name() const { return __name; } @@ -81,6 +90,8 @@ namespace std // type. Uniqueness must use the _name value, not object address. bool operator==(const type_info& __arg) const; #else + /** Returns true if @c *this preceeds @c __arg in the implementation's + * collation order. */ // In new abi we can rely on type_info's NTBS being unique, // and therefore address comparisons are sufficient. bool before(const type_info& __arg) const @@ -112,6 +123,8 @@ namespace std void **__obj_ptr) const; }; + /** If you attempt an invalid @c dynamic_cast expression, an instance of + * this class (or something derived from this class) is thrown. */ class bad_cast : public exception { public: @@ -119,6 +132,7 @@ namespace std virtual ~bad_cast() throw(); }; + /** If you use a NULL pointer in a @c typeid expression, this is thrown. */ class bad_typeid : public exception { public: -- 2.30.2