This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[v3] doxygen comments, libmath copyright fix
- To: gcc-patches at gcc dot gnu dot org
- Subject: [v3] doxygen comments, libmath copyright fix
- From: Phil Edwards <pedwards at disaster dot jaj dot com>
- Date: Wed, 11 Jul 2001 15:42:31 -0400
This is the first of what we hope will be a long series of patches adding
documentation to comments in a style that the Doxygen tool can find. It also
fixes the copyright for the libmath subdirectory's Makefile.am (approved
by Gaby and Benjamin). The comment there is the kind that doesn't get
passed through by automake, so there's no point in regenerating Makefile.in.
Trunk and branch. Nothing changed but comments, but it's been bootstrapping
for the last few days anyhow.
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.
Index: docs/doxygen/run_doxygen
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/run_doxygen,v
retrieving revision 1.5
diff -u -3 -p -r1.5 run_doxygen
--- run_doxygen 2001/06/11 13:04:07 1.5
+++ run_doxygen 2001/07/11 19:33:19
@@ -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
Index: docs/doxygen/user.cfg.in
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/user.cfg.in,v
retrieving revision 1.6
diff -u -3 -p -r1.6 user.cfg.in
--- user.cfg.in 2001/05/30 21:54:55 1.6
+++ user.cfg.in 2001/07/11 19:33:19
@@ -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
Index: include/bits/c++config
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/c++config,v
retrieving revision 1.43
diff -u -3 -p -r1.43 c++config
--- c++config 2001/07/11 07:16:10 1.43
+++ c++config 2001/07/11 19:33:20
@@ -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.
Index: include/bits/char_traits.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/char_traits.h,v
retrieving revision 1.9
diff -u -3 -p -r1.9 char_traits.h
--- char_traits.h 2001/06/11 04:36:59 1.9
+++ char_traits.h 2001/07/11 19:33:20
@@ -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<class _CharT>
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<char>
{
Index: include/bits/limits_generic.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/limits_generic.h,v
retrieving revision 1.3
diff -u -3 -p -r1.3 limits_generic.h
--- limits_generic.h 2001/06/12 22:14:08 1.3
+++ limits_generic.h 2001/07/11 19:33:20
@@ -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<typename _T> struct numeric_limits {
static const bool is_specialized = false;
Index: include/bits/std_stdexcept.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/std_stdexcept.h,v
retrieving revision 1.6
diff -u -3 -p -r1.6 std_stdexcept.h
--- std_stdexcept.h 2001/02/27 23:00:35 1.6
+++ std_stdexcept.h 2001/07/11 19:33:20
@@ -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:
Index: include/bits/stl_pair.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/stl_pair.h,v
retrieving revision 1.7
diff -u -3 -p -r1.7 stl_pair.h
--- stl_pair.h 2001/06/27 17:09:52 1.7
+++ stl_pair.h 2001/07/11 19:33:20
@@ -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 <class _T1, class _T2>
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 <class _U1, class _U2>
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 <class _T1, class _T2>
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 <class _T1, class _T2>
inline bool operator<(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y)
{
@@ -95,26 +103,39 @@ inline bool operator<(const pair<_T1, _T
(!(__y.first < __x.first) && __x.second < __y.second);
}
+/// Uses @c operator== to find the result.
template <class _T1, class _T2>
inline bool operator!=(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) {
return !(__x == __y);
}
+/// Uses @c operator< to find the result.
template <class _T1, class _T2>
inline bool operator>(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) {
return __y < __x;
}
+/// Uses @c operator< to find the result.
template <class _T1, class _T2>
inline bool operator<=(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) {
return !(__y < __x);
}
+/// Uses @c operator< to find the result.
template <class _T1, class _T2>
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 <class _T1, class _T2>
#ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
//181. make_pair() unintended behavior
Index: libmath/Makefile.am
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/libmath/Makefile.am,v
retrieving revision 1.13
diff -u -3 -p -r1.13 Makefile.am
--- Makefile.am 2001/07/06 23:09:30 1.13
+++ Makefile.am 2001/07/11 19:33:20
@@ -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.
Index: libsupc++/exception
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/libsupc++/exception,v
retrieving revision 1.4
diff -u -3 -p -r1.4 exception
--- exception 2001/03/13 19:32:00 1.4
+++ exception 2001/07/11 19:33:20
@@ -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
Index: libsupc++/new
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/libsupc++/new,v
retrieving revision 1.4
diff -u -3 -p -r1.4 new
--- new 2001/03/13 19:32:00 1.4
+++ new 2001/07/11 19:33:20
@@ -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
// 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
Index: libsupc++/typeinfo
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/libsupc++/typeinfo,v
retrieving revision 1.6
diff -u -3 -p -r1.6 typeinfo
--- typeinfo 2001/03/13 19:32:00 1.6
+++ typeinfo 2001/07/11 19:33:20
@@ -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: