Patchwork [v3] Doxygen improvements for Type Traits and Utilities

login
register
mail settings
Submitter Jonathan Wakely
Date Dec. 4, 2011, 4:56 p.m.
Message ID <CAH6eHdT5yX_EY=nyQiKxFY++G70XzQ4mkh_h6xO075tVRV_oNg@mail.gmail.com>
Download mbox | patch
Permalink /patch/129174/
State New
Headers show

Comments

Jonathan Wakely - Dec. 4, 2011, 4:56 p.m.
This patch declares the Type Traits doxygen group in <type_traits> not
in <tr1/type_traits> *and* <tr2/type_traits>. It also makes sure
doxygen comments are attached to the actual trait such as
is_member_pointer, not a helper such as __is_member_pointer_helper.  I
added brief descriptions for some of the less self-explanatory traits
(enable_if, conditional, declval) as well as for std::forward and
altered the std::move comment to say it converts to an rvalue, since
it's not really true to say it moves a value (that depends what the
caller does with the result.)

        * include/std/type_traits: Doxygen improvements.
        * include/bits/move.h: Likewise.
        * include/tr1/type_traits:  Likewise.
        * include/tr2/type_traits:  Likewise.
        * testsuite/20_util/declval/requirements/1_neg.cc: Adjust dg-error
        line numbers
        * testsuite/20_util/forward/c_neg.cc: Likewise.
        * testsuite/20_util/forward/f_neg.cc: Likewise.
        * testsuite/20_util/make_signed/requirements/typedefs_neg.cc:
        Likewise.
        * testsuite/20_util/make_unsigned/requirements/typedefs_neg.cc:
        Likewise.

Tested x86-64-linux with "make check" and "make doc-html" - committed to trunk.

Patch

Index: include/std/type_traits
===================================================================
--- include/std/type_traits	(revision 181992)
+++ include/std/type_traits	(revision 181993)
@@ -1,4 +1,4 @@ 
-// C++0x type_traits -*- C++ -*-
+// C++11 type_traits -*- C++ -*-
 
 // Copyright (C) 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
 //
@@ -42,7 +42,13 @@  namespace std _GLIBCXX_VISIBILITY(defaul
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   /**
-   * @addtogroup metaprogramming
+   * @defgroup metaprogramming Metaprogramming and type traits
+   * @ingroup utilities
+   *
+   * Template utilities for compile-time introspection and modification,
+   * including type classification traits, type property inspection traits
+   * and type transformation traits.
+   *
    * @{
    */
 
@@ -56,10 +62,10 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
       constexpr operator value_type() { return value; }
     };
   
-  /// typedef for true_type
+  /// The type used as a compile-time boolean with true value.
   typedef integral_constant<bool, true>     true_type;
 
-  /// typedef for false_type
+  /// The type used as a compile-time boolean with false value.
   typedef integral_constant<bool, false>    false_type;
 
   template<typename _Tp, _Tp __v>
@@ -451,7 +457,6 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
     struct is_compound
     : public integral_constant<bool, !is_fundamental<_Tp>::value> { };
 
-  /// is_member_pointer
   template<typename _Tp>
     struct __is_member_pointer_helper
     : public false_type { };
@@ -460,6 +465,7 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
     struct __is_member_pointer_helper<_Tp _Cp::*>
     : public true_type { };
 
+  /// is_member_pointer
   template<typename _Tp>
     struct is_member_pointer
     : public integral_constant<bool, (__is_member_pointer_helper<
@@ -492,7 +498,7 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
     : public integral_constant<bool, __is_trivial(_Tp)>
     { };
 
-  /// is_trivially_copyable (still unimplemented)
+  // is_trivially_copyable (still unimplemented)
 
   /// is_standard_layout
   template<typename _Tp>
@@ -564,6 +570,10 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
   template<typename>
     struct add_rvalue_reference;
 
+  /**
+   *  @brief  Utility to simplify expressions used in unevaluated operands
+   *  @ingroup utilities
+   */
   template<typename _Tp>
     typename add_rvalue_reference<_Tp>::type declval() noexcept;
 
@@ -1702,9 +1712,8 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
     };
 
 
-  // Define a nested type if some predicate holds.
   // Primary template.
-  /// enable_if
+  /// Define a member typedef @c type only if a boolean constant is true.
   template<bool, typename _Tp = void>
     struct enable_if 
     { };
@@ -1715,9 +1724,8 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
     { typedef _Tp type; };
 
 
-  // A conditional expression, but for types. If true, first, if false, second.
   // Primary template.
-  /// conditional
+  /// Define a member typedef @c type to one of two argument types.
   template<bool _Cond, typename _Iftrue, typename _Iffalse>
     struct conditional
     { typedef _Iftrue type; };
@@ -1747,14 +1755,13 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
         common_type<typename common_type<_Tp, _Up>::type, _Vp...>::type type;
     };
 
-  /// underlying_type
+  /// The underlying type of an enum.
   template<typename _Tp>
     struct underlying_type
     {
       typedef __underlying_type(_Tp) type;
     };
 
-  /// declval
   template<typename _Tp>
     struct __declval_protector
     {
@@ -1892,7 +1899,7 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
 			<typename remove_cv<_Tp>::type>::value>  \
     { };
 
-  // @} group metaprogramming
+  /// @} group metaprogramming
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace
 
Index: include/bits/move.h
===================================================================
--- include/bits/move.h	(revision 181992)
+++ include/bits/move.h	(revision 181993)
@@ -38,6 +38,10 @@  namespace std _GLIBCXX_VISIBILITY(defaul
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   // Used, in C++03 mode too, by allocators, etc.
+  /**
+   *  @brief Same as C++11 std::addressof
+   *  @ingroup utilities
+   */
   template<typename _Tp>
     inline _Tp*
     __addressof(_Tp& __r) _GLIBCXX_NOEXCEPT
@@ -55,13 +59,30 @@  _GLIBCXX_END_NAMESPACE_VERSION
 namespace std _GLIBCXX_VISIBILITY(default)
 {
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
-  
-  /// forward (as per N3143)
+
+  /**
+   *  @addtogroup utilities
+   *  @{
+   */
+
+  // forward (as per N3143)
+  /**
+   *  @brief  Forward an lvalue.
+   *  @return The parameter cast to the specified type.
+   *
+   *  This function is used to implement "perfect forwarding".
+   */
   template<typename _Tp>
     constexpr _Tp&&
     forward(typename std::remove_reference<_Tp>::type& __t) noexcept
     { return static_cast<_Tp&&>(__t); }
 
+  /**
+   *  @brief  Forward an rvalue.
+   *  @return The parameter cast to the specified type.
+   *
+   *  This function is used to implement "perfect forwarding".
+   */
   template<typename _Tp>
     constexpr _Tp&&
     forward(typename std::remove_reference<_Tp>::type&& __t) noexcept
@@ -72,10 +93,9 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
     }
 
   /**
-   *  @brief Move a value.
-   *  @ingroup utilities
+   *  @brief  Convert a value to an rvalue.
    *  @param  __t  A thing of arbitrary type.
-   *  @return Same, moved.
+   *  @return The parameter cast to an rvalue-reference to allow moving it.
   */
   template<typename _Tp>
     constexpr typename std::remove_reference<_Tp>::type&&
@@ -89,10 +109,12 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
                     is_copy_constructible<_Tp>>::type { };
 
   /**
-   *  @brief Move unless it could throw and the type is copyable.
-   *  @ingroup utilities
+   *  @brief  Conditionally convert a value to an rvalue.
    *  @param  __x  A thing of arbitrary type.
-   *  @return Same, possibly moved.
+   *  @return The parameter, possibly cast to an rvalue-reference.
+   *
+   *  Same as std::move unless the type's move constructor could throw and the
+   *  type is copyable, in which case an lvalue-reference is returned instead.
    */
   template<typename _Tp>
     inline typename
@@ -100,13 +122,12 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
     move_if_noexcept(_Tp& __x) noexcept
     { return std::move(__x); }
 
-  /// declval, from type_traits.
+  // declval, from type_traits.
 
   /**
    *  @brief Returns the actual address of the object or function
    *         referenced by r, even in the presence of an overloaded
    *         operator&.
-   *  @ingroup utilities
    *  @param  __r  Reference to an object or function.
    *  @return   The actual address.
   */
@@ -115,6 +136,7 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
     addressof(_Tp& __r) noexcept
     { return std::__addressof(__r); }
 
+  /// @} group utilities
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace
 
@@ -130,8 +152,12 @@  namespace std _GLIBCXX_VISIBILITY(defaul
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   /**
+   *  @addtogroup utilities
+   *  @{
+   */
+
+  /**
    *  @brief Swaps two values.
-   *  @ingroup utilities
    *  @param  __a  A thing of arbitrary type.
    *  @param  __b  Another thing of arbitrary type.
    *  @return   Nothing.
@@ -154,6 +180,7 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   // _GLIBCXX_RESOLVE_LIB_DEFECTS
   // DR 809. std::swap should be overloaded for array types.
+  /// Swap the contents of two arrays.
   template<typename _Tp, size_t _Nm>
     inline void
     swap(_Tp (&__a)[_Nm], _Tp (&__b)[_Nm])
@@ -165,6 +192,7 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	swap(__a[__n], __b[__n]);
     }
 
+  /// @} group utilities
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace
 
Index: include/tr1/type_traits
===================================================================
--- include/tr1/type_traits	(revision 181992)
+++ include/tr1/type_traits	(revision 181993)
@@ -1,6 +1,6 @@ 
 // TR1 type_traits -*- C++ -*-
 
-// Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010
+// Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
 // Free Software Foundation, Inc.
 //
 // This file is part of the GNU ISO C++ Library.  This library is free
@@ -41,10 +41,7 @@  namespace tr1
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   /**
-   * @defgroup metaprogramming Type Traits
-   * @ingroup utilities
-   *
-   * Compile time type transformation and information.
+   * @addtogroup metaprogramming
    * @{
    */
 
@@ -682,6 +679,8 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #undef _DEFINE_SPEC_2_HELPER
 #undef _DEFINE_SPEC
 
+  /// @} group metaprogramming
+
 _GLIBCXX_END_NAMESPACE_VERSION
 }
 }
Index: include/tr2/type_traits
===================================================================
--- include/tr2/type_traits	(revision 181992)
+++ include/tr2/type_traits	(revision 181993)
@@ -40,9 +40,7 @@  namespace tr2
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   /**
-   * @defgroup metaprogramming Type Traits
-   * @ingroup utilities
-   *
+   * @addtogroup metaprogramming
    * @{
    */
 
@@ -111,6 +109,8 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
       typedef typelist<__direct_bases(_Tp)...> 	type;
     };
 
+  /// @} group metaprogramming
+
 _GLIBCXX_END_NAMESPACE_VERSION
 }
 }
Index: ChangeLog
===================================================================
--- ChangeLog	(revision 181992)
+++ ChangeLog	(revision 181993)
@@ -1,3 +1,18 @@ 
+2011-12-04  Jonathan Wakely  <jwakely.gcc@gmail.com>
+
+	* include/std/type_traits: Doxygen improvements.
+	* include/bits/move.h: Likewise.
+	* include/tr1/type_traits:  Likewise.
+	* include/tr2/type_traits:  Likewise.
+	* testsuite/20_util/declval/requirements/1_neg.cc: Adjust dg-error
+	line numbers
+	* testsuite/20_util/forward/c_neg.cc: Likewise.
+	* testsuite/20_util/forward/f_neg.cc: Likewise.
+	* testsuite/20_util/make_signed/requirements/typedefs_neg.cc:
+	Likewise.
+	* testsuite/20_util/make_unsigned/requirements/typedefs_neg.cc:
+	Likewise.
+
 2011-12-04  Markus Trippelsdorf <markus@trippelsdorf.de>
             Jonathan Wakely  <jwakely.gcc@gmail.com>
 
Index: testsuite/20_util/make_signed/requirements/typedefs_neg.cc
===================================================================
--- testsuite/20_util/make_signed/requirements/typedefs_neg.cc	(revision 181992)
+++ testsuite/20_util/make_signed/requirements/typedefs_neg.cc	(revision 181993)
@@ -48,5 +48,5 @@  void test01()
 // { dg-error "required from here" "" { target *-*-* } 40 }
 // { dg-error "required from here" "" { target *-*-* } 42 }
 
-// { dg-error "invalid use of incomplete type" "" { target *-*-* } 1555 }
-// { dg-error "declaration of" "" { target *-*-* } 1519 }
+// { dg-error "invalid use of incomplete type" "" { target *-*-* } 1565 }
+// { dg-error "declaration of" "" { target *-*-* } 1529 }
Index: testsuite/20_util/make_unsigned/requirements/typedefs_neg.cc
===================================================================
--- testsuite/20_util/make_unsigned/requirements/typedefs_neg.cc	(revision 181992)
+++ testsuite/20_util/make_unsigned/requirements/typedefs_neg.cc	(revision 181993)
@@ -48,5 +48,5 @@  void test01()
 // { dg-error "required from here" "" { target *-*-* } 40 }
 // { dg-error "required from here" "" { target *-*-* } 42 }
 
-// { dg-error "invalid use of incomplete type" "" { target *-*-* } 1473 }
-// { dg-error "declaration of" "" { target *-*-* } 1437 }
+// { dg-error "invalid use of incomplete type" "" { target *-*-* } 1483 }
+// { dg-error "declaration of" "" { target *-*-* } 1447 }
Index: testsuite/20_util/declval/requirements/1_neg.cc
===================================================================
--- testsuite/20_util/declval/requirements/1_neg.cc	(revision 181992)
+++ testsuite/20_util/declval/requirements/1_neg.cc	(revision 181993)
@@ -19,7 +19,7 @@ 
 // with this library; see the file COPYING3.  If not see
 // <http://www.gnu.org/licenses/>.
 
-// { dg-error "static assertion failed" "" { target *-*-* } 1769 }
+// { dg-error "static assertion failed" "" { target *-*-* } 1776 }
 
 #include <utility>
 
Index: testsuite/20_util/forward/c_neg.cc
===================================================================
--- testsuite/20_util/forward/c_neg.cc	(revision 181992)
+++ testsuite/20_util/forward/c_neg.cc	(revision 181993)
@@ -18,7 +18,7 @@ 
 // with this library; see the file COPYING3.  If not see
 // <http://www.gnu.org/licenses/>.
 
-// { dg-error "static assertion failed" "" { target *-*-* } 69 }
+// { dg-error "static assertion failed" "" { target *-*-* } 90 }
 
 #include <list>
 
Index: testsuite/20_util/forward/f_neg.cc
===================================================================
--- testsuite/20_util/forward/f_neg.cc	(revision 181992)
+++ testsuite/20_util/forward/f_neg.cc	(revision 181993)
@@ -1,7 +1,7 @@ 
 // { dg-do compile }
 // { dg-options "-std=gnu++0x" }
 
-// Copyright (C) 2010 Free Software Foundation, Inc.
+// Copyright (C) 2010, 2011 Free Software Foundation, Inc.
 //
 // This file is part of the GNU ISO C++ Library.  This library is free
 // software; you can redistribute it and/or modify it under the
@@ -18,7 +18,7 @@ 
 // with this library; see the file COPYING3.  If not see
 // <http://www.gnu.org/licenses/>.
 
-// { dg-error "static assertion failed" "" { target *-*-* } 69 }
+// { dg-error "static assertion failed" "" { target *-*-* } 90 }
 
 #include <utility>