re PR libstdc++/17218 (unknown subjects in generated libstdc++ manpages)

2004-11-05  Benjamin Kosnik  <bkoz@redhat.com>

	PR libstdc++/17218
	PR libstdc++/17223
	* docs/doxygen/filter: Remove.
	* docs/doxygen/filter.sed: Remove.
	* docs/doxygen/mainpage.html: Add link to functions.
	* docs/doxygen/run_doxygen: Changes due to new source filtering.
	* docs/doxygen/user.cfg.in: Update to doxygen 1.3.9.1, tweak.
	* include/bits/allocator.h: Tweaks for doxygen.
	* include/bits/char_traits.h: Same.
	* include/bits/codecvt.h: Same.
	* include/bits/concurrence.h: Same.
	* include/bits/locale_facets.h: Same.
	* include/ext/array_allocator.h: Same.
	* include/ext/debug_allocator.h: Same.
	* include/ext/malloc_allocator.h: Same.
	* include/ext/mt_allocator.h: Same.
	* include/ext/new_allocator.h: Same.
	* include/ext/pool_allocator.h: Same.
	* include/ext/stdio_sync_filebuf.h: Same.
	* include/std/std_memory.h: Same.
	* include/tr1/array: Same.
	* include/tr1/tuple: Same.
	* config/locale/ieee_1003.1-2001/codecvt_specializations.h: Same.
	* config/os/gnu-linux/ctype_base.h: Same.

From-SVN: r90137

libstdc++-v3/ChangeLog

+2004-11-05  Benjamin Kosnik  <bkoz@redhat.com>
+
+	PR libstdc++/17218
+	PR libstdc++/17223
+	* docs/doxygen/filter: Remove.
+	* docs/doxygen/filter.sed: Remove.
+	* docs/doxygen/mainpage.html: Add link to functions.
+	* docs/doxygen/run_doxygen: Changes due to new source filtering.
+	* docs/doxygen/user.cfg.in: Update to doxygen 1.3.9.1, tweak.
+	* include/bits/allocator.h: Tweaks for doxygen.
+	* include/bits/char_traits.h: Same.
+	* include/bits/codecvt.h: Same.
+	* include/bits/concurrence.h: Same.
+	* include/bits/locale_facets.h: Same.
+	* include/ext/array_allocator.h: Same.
+	* include/ext/debug_allocator.h: Same.
+	* include/ext/malloc_allocator.h: Same.
+	* include/ext/mt_allocator.h: Same.
+	* include/ext/new_allocator.h: Same.
+	* include/ext/pool_allocator.h: Same.
+	* include/ext/stdio_sync_filebuf.h: Same.
+	* include/std/std_memory.h: Same.
+	* include/tr1/array: Same.
+	* include/tr1/tuple: Same.
+	* config/locale/ieee_1003.1-2001/codecvt_specializations.h: Same.
+	* config/os/gnu-linux/ctype_base.h: Same.
+
 2004-11-04  Paolo Carlini  <pcarlini@suse.de>
 
 	* include/bits/locale_facets.tcc (num_get<>::do_get(bool&)):

libstdc++-v3/config/locale/ieee_1003.1-2001/codecvt_specializations.h

@@ -39,8 +39,8 @@
   // Define this here so codecvt.cc can have _S_max_size definition.
 #define _GLIBCXX_USE___ENC_TRAITS 1
 
-  // Extension to use icov for dealing with character encodings,
-  // including conversions and comparisons between various character
+  /// @brief  Extension to use icov for dealing with character encodings.
+  // This includes conversions and comparisons between various character
   // sets.  This object encapsulates data that may need to be shared between
   // char_traits, codecvt and ctype.
   class __enc_traits
@@ -192,7 +192,7 @@
     { return _M_ext_enc; }    
   };
 
-  // Partial specialization
+  /// Partial specialization.
   // This specialization takes advantage of iconv to provide code
   // conversions between a large number of character encodings.
   template<typename _InternT, typename _ExternT>

libstdc++-v3/config/os/gnu-linux/ctype_base.h

@@ -34,6 +34,7 @@
   
 // Information as gleaned from /usr/include/ctype.h
   
+  /// @brief  Base class for ctype.
   struct ctype_base
   {
     // Non-standard typedefs.

libstdc++-v3/docs/doxygen/filter

-#!/bin/sh
-
-script=$1
-file=$2
-
-# Possibly allow some files to go unchanged.  Other
-# future manipulations are likely.
-case $file in
- */alloc_policies.h)
-  cat $file ;;
- *) sed -f $script $file ;;
-esac
-

libstdc++-v3/docs/doxygen/filter.sed

-# Input filter for doxygen.
-# Copyright (C) 2003, 2004 Free Software Foundation, Inc.
-# Phil Edwards <pme@gcc.gnu.org>
-
-# single+capital is easy
-s/_Tp/Type/g
-s/_\([A-Z]\)/\1/g
-
-# double+lower is not so easy; some names should be left alone.
-# The following is a sloppy start.  Possibly just require GNU tools
-# and use extensions.
-s/__a/a/g
-s/__c/c/g
-s/__first/first/g
-s/__in/in/g
-s/__last/last/g
-s/__n/n/g
-s/__out/out/g
-s/__pred/pred/g
-s/__position/position/g
-s/__pos/position/g
-s/__s/s/g
-s/__value/value/g
-s/__x/x/g
-s/__y/y/g
-s/GLIBCXXSTD/std/g

libstdc++-v3/docs/doxygen/mainpage.html

@@ -45,10 +45,11 @@
 <p>Here are entry points to all the pages generated by Doxygen:
    <ul>
     <li><a href="modules.html">Modules</a>
-    <li><a href="namespaces.html">Namespace List</a>
     <li><a href="hierarchy.html">Class List</a>
     <li><a href="annotated.html">Class Annotated List</a>
     <li><a href="classes.html">Class Alphabetical Index</a>
+    <li><a href="globals_func.html">Function Alphabetical List</a>
+    <li><a href="namespaces.html">Namespace List</a>
     <li><a href="files.html">Source File List</a>
     <li><a href="todo.html">TODO List</a> (This is incomplete... how ironic.)
    </ul>

libstdc++-v3/docs/doxygen/run_doxygen

@@ -279,15 +279,18 @@ for f in __gnu_cxx_*; do
     newname=`echo $f | sed 's/^__gnu_cxx_/__gnu_cxx::/'`
     mv $f $newname
 done
-for f in __gnu_debug_*; do
-    newname=`echo $f | sed 's/^__gnu_debug_/__gnu_debug::/'`
-    mv $f $newname
+
+# Generic reoval bits, where there are things in the generated man
+# pages that need to be killed.
+for f in *_libstdc__-v3_*; do
+    rm $f 
 done
-for f in GLIBCXXSTD_*; do
-    newname=`echo $f | sed 's/^GLIBCXXSTD_/std::/'`
-    mv $f $newname
+
+for f in *_src_*; do
+    rm $f 
 done
 
+
 # Also, for some reason, typedefs don't get their own man pages.  Sigh.
 for f in ios streambuf istream ostream iostream stringbuf \
          istringstream ostringstream stringstream filebuf ifstream \

libstdc++-v3/include/bits/allocator.h

@@ -71,11 +71,7 @@ namespace std
         { typedef allocator<_Tp1> other; };
     };
 
-  /**
-   *  @brief  The "standard" allocator, as per [20.4].
-   *
-   *  (See @link Allocators allocators info @endlink for more.)
-   */
+  /// @brief  The "standard" allocator, as per [20.4].
   template<typename _Tp>
     class allocator: public ___glibcxx_base_allocator<_Tp>
     {

libstdc++-v3/include/bits/char_traits.h

@@ -51,7 +51,6 @@ namespace __gnu_cxx
   /**
    *  @brief  Mapping from character type to associated types.
    *
-   *
    *  @note This is an implementation class for the generic version
    *  of char_traits.  It defines int_type, off_type, pos_type, and
    *  state_type.  By default these are unsigned long, streamoff,
@@ -82,7 +81,8 @@ namespace __gnu_cxx
    *
    *  See http://gcc.gnu.org/onlinedocs/libstdc++/21_strings/howto.html#5
    *  for advice on how to make use of this class for "unusual" character
-   *  types. Also, check out include/ext/pod_char_traits.h.  */
+   *  types. Also, check out include/ext/pod_char_traits.h.  
+   */
   template<typename _CharT>
     struct char_traits
     {
@@ -222,12 +222,11 @@ namespace std
    *  types. Also, check out include/ext/pod_char_traits.h.
   */
   template<class _CharT>
-    struct char_traits
-    : public __gnu_cxx::char_traits<_CharT>
+    struct char_traits : public __gnu_cxx::char_traits<_CharT>
     { };
 
 
-  /// 21.1.3.1  char_traits specializations
+  /// @brief  21.1.3.1  char_traits specializations
   template<>
     struct char_traits<char>
     {
@@ -297,7 +296,7 @@ namespace std
 
 
 #ifdef _GLIBCXX_USE_WCHAR_T
-  /// 21.1.3.2  char_traits specializations
+  /// @brief  21.1.3.2  char_traits specializations
   template<>
     struct char_traits<wchar_t>
     {

libstdc++-v3/include/bits/codecvt.h

@@ -44,7 +44,9 @@
 #pragma GCC system_header
 
   //  22.2.1.5  Template class codecvt
-  /// Base class for codecvt facet providing conversion result enum.
+  /**
+   *  @brief  Base class for codecvt facet providing conversion result enum.
+   */
   class codecvt_base
   {
   public:
@@ -102,11 +104,12 @@
        *  beginning and carried from a previous call if continuing
        *  conversion.  There are no guarantees about how @a state is used.
        *
-       *  The result returned is a member of codecvt_base::result.  If all the
-       *  input is converted, returns codecvt_base::ok.  If no conversion is
-       *  necessary, returns codecvt_base::noconv.  If the input ends early or
-       *  there is insufficient space in the output, returns codecvt_base::partial.
-       *  Otherwise the conversion failed and codecvt_base::error is returned.
+       *  The result returned is a member of codecvt_base::result.  If
+       *  all the input is converted, returns codecvt_base::ok.  If no
+       *  conversion is necessary, returns codecvt_base::noconv.  If
+       *  the input ends early or there is insufficient space in the
+       *  output, returns codecvt_base::partial.  Otherwise the
+       *  conversion failed and codecvt_base::error is returned.
        *
        *  @param  state  Persistent conversion state data.
        *  @param  from  Start of input.
@@ -181,11 +184,12 @@
        *  beginning and carried from a previous call if continuing
        *  conversion.  There are no guarantees about how @a state is used.
        *
-       *  The result returned is a member of codecvt_base::result.  If all the
-       *  input is converted, returns codecvt_base::ok.  If no conversion is
-       *  necessary, returns codecvt_base::noconv.  If the input ends early or
-       *  there is insufficient space in the output, returns codecvt_base::partial.
-       *  Otherwise the conversion failed and codecvt_base::error is returned.
+       *  The result returned is a member of codecvt_base::result.  If
+       *  all the input is converted, returns codecvt_base::ok.  If no
+       *  conversion is necessary, returns codecvt_base::noconv.  If
+       *  the input ends early or there is insufficient space in the
+       *  output, returns codecvt_base::partial.  Otherwise the
+       *  conversion failed and codecvt_base::error is returned.
        *
        *  @param  state  Persistent conversion state data.
        *  @param  from  Start of input.
@@ -267,7 +271,7 @@
       do_max_length() const throw() = 0;
     };
 
-  // 22.2.1.5 Template class codecvt
+  /// @brief  22.2.1.5 Template class codecvt
   // NB: Generic, mostly useless implementation.
   template<typename _InternT, typename _ExternT, typename _StateT>
     class codecvt
@@ -330,7 +334,7 @@
   template<typename _InternT, typename _ExternT, typename _StateT>
     locale::id codecvt<_InternT, _ExternT, _StateT>::id;
 
-  // codecvt<char, char, mbstate_t> required specialization
+  /// @brief  codecvt<char, char, mbstate_t> required specialization
   template<>
     class codecvt<char, char, mbstate_t>
     : public __codecvt_abstract_base<char, char, mbstate_t>
@@ -388,7 +392,7 @@
   };
 
 #ifdef _GLIBCXX_USE_WCHAR_T
-  // codecvt<wchar_t, char, mbstate_t> required specialization
+  /// @brief  codecvt<wchar_t, char, mbstate_t> required specialization
   template<>
     class codecvt<wchar_t, char, mbstate_t>
     : public __codecvt_abstract_base<wchar_t, char, mbstate_t>
@@ -448,7 +452,7 @@
     };
 #endif //_GLIBCXX_USE_WCHAR_T
 
-  // 22.2.1.6  Template class codecvt_byname
+  /// @brief  22.2.1.6  Template class codecvt_byname
   template<typename _InternT, typename _ExternT, typename _StateT>
     class codecvt_byname : public codecvt<_InternT, _ExternT, _StateT>
     {

libstdc++-v3/include/bits/concurrence.h

@@ -71,10 +71,10 @@ namespace __gnu_cxx
 {
   typedef __glibcxx_mutex_type mutex_type;
   
-  // Scoped lock idiom.
+  /// @brief  Scoped lock idiom.
   // Acquire the mutex here with a constructor call, then release with
   // the destructor call in accordance with RAII style.
-   class lock
+  class lock
   {
     // Externally defined and initialized.
     mutex_type& device;

libstdc++-v3/include/bits/locale_facets.h

@@ -1511,7 +1511,7 @@ namespace std
   // Include host and configuration specific ctype inlines.
   #include <bits/ctype_inline.h>
 
-  // 22.2.1.2  Template class ctype_byname
+  /// @brief  22.2.1.2  Template class ctype_byname
   template<typename _CharT>
     class ctype_byname : public ctype<_CharT>
     {

libstdc++-v3/include/ext/array_allocator.h

@@ -37,6 +37,7 @@
 
 namespace __gnu_cxx
 {
+  /// @brief  Base class.
  template<typename _Tp>
     class array_allocator_base
     {
@@ -78,8 +79,6 @@ namespace __gnu_cxx
   /**
    *  @brief  An allocator that uses previously allocated memory.
    *  This memory can be externally, globally, or otherwise allocated.
-   *
-   *  (See @link Allocators allocators info @endlink for more.)
    */
   template<typename _Tp, typename _Array = std::tr1::array<_Tp> >
     class array_allocator : public array_allocator_base<_Tp>

libstdc++-v3/include/ext/debug_allocator.h

@@ -58,8 +58,6 @@ namespace __gnu_cxx
    *  This is precisely the allocator defined in the C++ Standard. 
    *    - all allocation calls operator new
    *    - all deallocation calls operator delete
-   *
-   *  (See @link Allocators allocators info @endlink for more.)
    */
   template<typename _Alloc>
     class debug_allocator

libstdc++-v3/include/ext/malloc_allocator.h

@@ -41,8 +41,6 @@ namespace __gnu_cxx
    *  This is precisely the allocator defined in the C++ Standard. 
    *    - all allocation calls malloc
    *    - all deallocation calls free
-   *
-   *  (See @link Allocators allocators info @endlink for more.)
    */
   template<typename _Tp>
     class malloc_allocator

libstdc++-v3/include/ext/mt_allocator.h

@@ -43,19 +43,10 @@
 
 namespace __gnu_cxx
 {
-  /**
-   *  This is a fixed size (power of 2) allocator which - when
-   *  compiled with thread support - will maintain one freelist per
-   *  size per thread plus a "global" one. Steps are taken to limit
-   *  the per thread freelist sizes (by returning excess back to
-   *  "global").
-   *
-   *  Further details:
-   *  http://gcc.gnu.org/onlinedocs/libstdc++/ext/mt_allocator.html
-   */
   typedef void (*__destroy_handler)(void*);
   typedef void (*__create_handler)(void);
 
+  /// @brief  Base class for pool object.
   struct __pool_base
   {
     // Using short int as type for the binmap implies we are never
@@ -187,8 +178,11 @@ namespace __gnu_cxx
     bool 			_M_init;
   };
 
-  // Data describing the underlying memory pool, parameterized on
-  // threading support.
+
+  /**
+   *  @brief  Data describing the underlying memory pool, parameterized on
+   *  threading support.
+   */
   template<bool _Thread>
     class __pool;
 
@@ -198,7 +192,7 @@ namespace __gnu_cxx
   template<>
     class __pool<false>;
 
-  // Specialization for single thread.
+  /// Specialization for single thread.
   template<>
     class __pool<false> : public __pool_base
     {
@@ -265,7 +259,7 @@ namespace __gnu_cxx
   };
  
 #ifdef __GTHREADS
-   // Specialization for thread enabled, via gthreads.h.
+  /// Specialization for thread enabled, via gthreads.h.
   template<>
     class __pool<true> : public __pool_base
     {
@@ -405,9 +399,11 @@ namespace __gnu_cxx
 #endif
 
 
+  /// @brief  Policy for shared __pool objects.
   template<template <bool> class _PoolTp, bool _Thread>
     struct __common_pool_policy;
 
+  /// Partial specialization for single thread.
   template<template <bool> class _PoolTp>
     struct __common_pool_policy<_PoolTp, false>
     {
@@ -438,6 +434,7 @@ namespace __gnu_cxx
     };
 
 #ifdef __GTHREADS
+  /// Partial specialization for thread enabled, via gthreads.h.
   template<template <bool> class _PoolTp>
     struct __common_pool_policy<_PoolTp, true>
     {
@@ -478,9 +475,11 @@ namespace __gnu_cxx
 #endif
 
  
+  /// @brief  Policy for individual __pool objects.
   template<typename _Tp, template <bool> class _PoolTp, bool _Thread>
     struct __per_type_pool_policy;
 
+  /// Partial specialization for single thread.
   template<typename _Tp, template <bool> class _PoolTp>
     struct __per_type_pool_policy<_Tp, _PoolTp, false>
     {
@@ -515,6 +514,7 @@ namespace __gnu_cxx
     };
 
 #ifdef __GTHREADS
+  /// Partial specialization for thread enabled, via gthreads.h.
   template<typename _Tp, template <bool> class _PoolTp>
     struct __per_type_pool_policy<_Tp, _PoolTp, true>
     {
@@ -558,6 +558,7 @@ namespace __gnu_cxx
     };
 #endif
 
+  /// @brief  Base class for _Tp dependent member functions.
   template<typename _Tp>
     class __mt_alloc_base 
     {
@@ -598,6 +599,16 @@ namespace __gnu_cxx
 #define __thread_default false
 #endif
 
+  /**
+   *  @brief  This is a fixed size (power of 2) allocator which - when
+   *  compiled with thread support - will maintain one freelist per
+   *  size per thread plus a "global" one. Steps are taken to limit
+   *  the per thread freelist sizes (by returning excess back to
+   *  the "global" list).
+   *
+   *  Further details:
+   *  http://gcc.gnu.org/onlinedocs/libstdc++/ext/mt_allocator.html
+   */
   template<typename _Tp, 
 	   typename _Poolp = __common_pool_policy<__pool, __thread_default> >
     class __mt_alloc : public __mt_alloc_base<_Tp>

libstdc++-v3/include/ext/new_allocator.h

@@ -41,8 +41,6 @@ namespace __gnu_cxx
    *  This is precisely the allocator defined in the C++ Standard. 
    *    - all allocation calls operator new
    *    - all deallocation calls operator delete
-   *
-   *  (See @link Allocators allocators info @endlink for more.)
    */
   template<typename _Tp>
     class new_allocator

libstdc++-v3/include/ext/pool_allocator.h

@@ -57,6 +57,8 @@
 namespace __gnu_cxx
 {
   /**
+   *  @brief  Base class for __pool_alloc.
+   *
    *  @if maint
    *  Uses various allocators to fulfill underlying requests (and makes as
    *  few requests as possible when in default high-speed pool mode).
@@ -71,7 +73,6 @@ namespace __gnu_cxx
    *     without permanently losing part of the object.
    *
    *  @endif
-   *  (See @link Allocators allocators info @endlink for more.)
    */
     class __pool_alloc_base
     {
@@ -116,6 +117,7 @@ namespace __gnu_cxx
     };
 
 
+  /// @brief  Class __pool_alloc.
   template<typename _Tp>
     class __pool_alloc : private __pool_alloc_base
     {

libstdc++-v3/include/ext/stdio_sync_filebuf.h

@@ -46,6 +46,7 @@
 
 namespace __gnu_cxx
 {
+  /// @brief  Class stdio_sync_filebuf.
   template<typename _CharT, typename _Traits = std::char_traits<_CharT> >
     class stdio_sync_filebuf : public std::basic_streambuf<_CharT, _Traits>
     {

libstdc++-v3/include/std/std_memory.h

@@ -336,7 +336,7 @@ namespace std
 	  }
       }
       
-      /** @{
+      /** 
        *  @brief  Automatic conversions
        *
        *  These operations convert an %auto_ptr into and from an auto_ptr_ref
@@ -368,7 +368,6 @@ namespace std
       template<typename _Tp1>
         operator auto_ptr<_Tp1>() throw()
         { return auto_ptr<_Tp1>(this->release()); }
-      /** @}  */
   };
 } // namespace std
 

libstdc++-v3/include/tr1/array

@@ -40,7 +40,7 @@ namespace std
 {
 namespace tr1
 {
-  // [6.2.2] Class template array template
+  /// @brief  [6.2.2] Class template array template
   // Requires complete type _Tp.
   template<typename _Tp, size_t _Nm = 1>
     struct array

libstdc++-v3/include/tr1/tuple

@@ -35,7 +35,7 @@ namespace tr1
   // when the tuple is not maximum possible size.
   struct _NullClass { };
 
-  // Foward definition of the tuple class
+  /// @brief  Foward definition of the tuple class.
   template<typename _Tp0 = _NullClass, typename _Tp1 = _NullClass,
 	   typename _Tp2 = _NullClass, typename _Tp3 = _NullClass,
 	   typename _Tp4 = _NullClass, typename _Tp5 = _NullClass,
@@ -43,7 +43,7 @@ namespace tr1
 	   typename _Tp8 = _NullClass, typename _Tp9 = _NullClass>
     class tuple;
 
-  // Gives the type of the ith element of a given tuple type.
+  /// @brief  Gives the type of the ith element of a given tuple type.
   template<int __i, typename _Tp>
     struct tuple_element;
 
@@ -117,7 +117,7 @@ namespace tr1
 				  _Tp7, _Tp8, _Tp9> >
     { typedef _Tp9 type; };
 
-  // Finds the size of a given tuple type.
+  /// @brief  Finds the size of a given tuple type.
   template<typename _Tp>
     struct tuple_size;