This is the mail archive of the libstdc++@gcc.gnu.org mailing list for the libstdc++ project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

[patch] Doxygen markup for 18, 19, part of 20



The number of diffs I have in my local tree is starting to become more
than what will fit in my head, largely over the past week.  So, please,
give me some feedback on this so I can get it into shape for checkin.

Some comments:

1)  In order for namespace-level functions to show up, we have to document
the namespace itself, otherwise doxygen just ignores the markup.  A 4-line
comment in c++config does this for us.  (No other file seemed appropriate.)

2)  Nearly all of the places where I've used /** comments instead of /// seem
to require it.  For example, if the 4-line comment is changed to ///-style
(which should be the same thing), doxygen doesn't see the documentation of
namespace std.  This means that two whole categories of stuff just vanishes
from the output (Namespace List (boring) and Namespace Members (important)).

3)  Using special commands (they start with a @) seems to work better
in the detailed mode (/** style) than in the brief mode (/// style).
Possibly certain commands are not meant to be placed in brief blocks,
I don't know.  Anyhow, where comments seemed to not be short, or had the
potential to grow, or used @-commands, I went with the /** detailed mode.
Yes, this would appear to suck in a C++ project, but there you have it.
(I found that reading the source comments wasn't so bad after a while.)


So far this represents one of everything, i.e., there's relatively little
code in 18 and 19, but what's below seems to cover all the situations
we're going to get into with other chapters.  I wanted to iron out wrinkles
before continuing with 20.


Phil


Index: include/bits/c++config
===================================================================
RCS file: /home/pme/Repositories/GCC/gcc/libstdc++-v3/include/bits/c++config,v
retrieving revision 1.41
diff -u -3 -r1.41 c++config
--- include/bits/c++config	2001/07/09 07:16:40	1.41
+++ include/bits/c++config	2001/07/09 20:16:08
@@ -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: /home/pme/Repositories/GCC/gcc/libstdc++-v3/include/bits/char_traits.h,v
retrieving revision 1.9
diff -u -3 -r1.9 char_traits.h
--- include/bits/char_traits.h	2001/06/11 04:36:59	1.9
+++ include/bits/char_traits.h	2001/07/09 20:44:02
@@ -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 @@
     };
 
 
-  // 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: /home/pme/Repositories/GCC/gcc/libstdc++-v3/include/bits/limits_generic.h,v
retrieving revision 1.3
diff -u -3 -r1.3 limits_generic.h
--- include/bits/limits_generic.h	2001/06/12 22:14:08	1.3
+++ include/bits/limits_generic.h	2001/07/09 20:27:28
@@ -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 @@
         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: /home/pme/Repositories/GCC/gcc/libstdc++-v3/include/bits/std_stdexcept.h,v
retrieving revision 1.6
diff -u -3 -r1.6 std_stdexcept.h
--- include/bits/std_stdexcept.h	2001/02/27 23:00:35	1.6
+++ include/bits/std_stdexcept.h	2001/07/09 21:20:00
@@ -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: /home/pme/Repositories/GCC/gcc/libstdc++-v3/include/bits/stl_pair.h,v
retrieving revision 1.7
diff -u -3 -r1.7 stl_pair.h
--- include/bits/stl_pair.h	2001/06/27 17:09:52	1.7
+++ include/bits/stl_pair.h	2001/07/09 20:22:48
@@ -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 @@
          (!(__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: libsupc++/exception
===================================================================
RCS file: /home/pme/Repositories/GCC/gcc/libstdc++-v3/libsupc++/exception,v
retrieving revision 1.4
diff -u -3 -r1.4 exception
--- libsupc++/exception	2001/03/13 19:32:00	1.4
+++ libsupc++/exception	2001/07/09 20:25:17
@@ -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 @@
 
 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 @@
     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: /home/pme/Repositories/GCC/gcc/libstdc++-v3/libsupc++/new,v
retrieving revision 1.4
diff -u -3 -r1.4 new
--- libsupc++/new	2001/03/13 19:32:00	1.4
+++ libsupc++/new	2001/06/28 21:07:12
@@ -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 @@
 
 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 @@
 
   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 @@
 // 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: /home/pme/Repositories/GCC/gcc/libstdc++-v3/libsupc++/typeinfo,v
retrieving revision 1.6
diff -u -3 -r1.6 typeinfo
--- libsupc++/typeinfo	2001/03/13 19:32:00	1.6
+++ libsupc++/typeinfo	2001/07/09 20:26:19
@@ -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 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 @@
     
   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 @@
     // 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 @@
 			     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 @@
     virtual ~bad_cast() throw();
   };
   
+  /** If you use a NULL pointer in a @c typeid expression, this is thrown.  */
   class bad_typeid : public exception 
   {
   public:
Index: docs/doxygen/run_doxygen
===================================================================
RCS file: /home/pme/Repositories/GCC/gcc/libstdc++-v3/docs/doxygen/run_doxygen,v
retrieving revision 1.5
diff -u -3 -r1.5 run_doxygen
--- docs/doxygen/run_doxygen	2001/06/11 13:04:07	1.5
+++ docs/doxygen/run_doxygen	2001/06/27 22:48:19
@@ -115,7 +115,9 @@
       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: /home/pme/Repositories/GCC/gcc/libstdc++-v3/docs/doxygen/user.cfg.in,v
retrieving revision 1.6
diff -u -3 -r1.6 user.cfg.in
--- docs/doxygen/user.cfg.in	2001/05/30 21:54:55	1.6
+++ docs/doxygen/user.cfg.in	2001/07/09 22:08:05
@@ -197,7 +197,7 @@
 # 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 @@
 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 Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]