[gcc r12-2998] libstdc++: Improve doxygen comments in <bits/stl_function.h>
Jonathan Wakely
redi@gcc.gnu.org
Wed Aug 18 14:36:29 GMT 2021
https://gcc.gnu.org/g:828176ba490d034d5d689f7733466530c25c5ed3
commit r12-2998-g828176ba490d034d5d689f7733466530c25c5ed3
Author: Jonathan Wakely <jwakely@redhat.com>
Date: Wed Aug 18 12:18:35 2021 +0100
libstdc++: Improve doxygen comments in <bits/stl_function.h>
Add notes about deprecation and modern replacements. Fix bogus
"memory_adaptors" group name. Use markdown for formatting.
Signed-off-by: Jonathan Wakely <jwakely@redhat.com>
libstdc++-v3/ChangeLog:
* include/bits/stl_function.h: Improve doxygen comments.
Diff:
---
libstdc++-v3/include/bits/stl_function.h | 134 +++++++++++++++++--------------
1 file changed, 74 insertions(+), 60 deletions(-)
diff --git a/libstdc++-v3/include/bits/stl_function.h b/libstdc++-v3/include/bits/stl_function.h
index 073018d522d..5de8c3234f7 100644
--- a/libstdc++-v3/include/bits/stl_function.h
+++ b/libstdc++-v3/include/bits/stl_function.h
@@ -66,40 +66,52 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 20.3.1 base classes
/** @defgroup functors Function Objects
- * @ingroup utilities
+ * @ingroup utilities
*
- * Function objects, or @e functors, are objects with an @c operator()
+ * Function objects, or _functors_, are objects with an `operator()`
* defined and accessible. They can be passed as arguments to algorithm
* templates and used in place of a function pointer. Not only is the
* resulting expressiveness of the library increased, but the generated
* code can be more efficient than what you might write by hand. When we
- * refer to @a functors, then, generally we include function pointers in
+ * refer to _functors_, then, generally we include function pointers in
* the description as well.
*
* Often, functors are only created as temporaries passed to algorithm
* calls, rather than being created as named variables.
*
* Two examples taken from the standard itself follow. To perform a
- * by-element addition of two vectors @c a and @c b containing @c double,
- * and put the result in @c a, use
+ * by-element addition of two vectors `a` and `b` containing `double`,
+ * and put the result in `a`, use
* \code
* transform (a.begin(), a.end(), b.begin(), a.begin(), plus<double>());
* \endcode
- * To negate every element in @c a, use
+ * To negate every element in `a`, use
* \code
* transform(a.begin(), a.end(), a.begin(), negate<double>());
* \endcode
- * The addition and negation functions will be inlined directly.
+ * The addition and negation functions will usually be inlined directly.
*
- * The standard functors are derived from structs named @c unary_function
- * and @c binary_function. These two classes contain nothing but typedefs,
- * to aid in generic (template) programming. If you write your own
- * functors, you might consider doing the same.
+ * An _adaptable function object_ is one which provides nested typedefs
+ * `result_type` and either `argument_type` (for a unary function) or
+ * `first_argument_type` and `second_argument_type` (for a binary function).
+ * Those typedefs are used by function object adaptors such as `bind2nd`.
+ * The standard library provides two class templates, `unary_function` and
+ * `binary_function`, which define those typedefs and so can be used as
+ * base classes of adaptable function objects.
+ *
+ * Since C++11 the use of function object adaptors has been superseded by
+ * more powerful tools such as lambda expressions, `function<>`, and more
+ * powerful type deduction (using `auto` and `decltype`). The helpers for
+ * defining adaptable function objects are deprecated since C++11, and no
+ * longer part of the standard library since C++17. However, they are still
+ * defined and used by libstdc++ after C++17, as a conforming extension.
*
* @{
*/
+
/**
- * This is one of the @link functors functor base classes@endlink.
+ * Helper for defining adaptable unary function objects.
+ * @deprecated Deprecated in C++11, no longer in the standard since C++17.
*/
template<typename _Arg, typename _Result>
struct unary_function
@@ -112,7 +124,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
};
/**
- * This is one of the @link functors functor base classes@endlink.
+ * Helper for defining adaptable binary function objects.
+ * @deprecated Deprecated in C++11, no longer in the standard since C++17.
*/
template<typename _Arg1, typename _Arg2, typename _Result>
struct binary_function
@@ -129,12 +142,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/** @} */
// 20.3.2 arithmetic
- /** @defgroup arithmetic_functors Arithmetic Classes
- * @ingroup functors
+
+ /** @defgroup arithmetic_functors Arithmetic Function Object Classes
+ * @ingroup functors
*
- * Because basic math often needs to be done during an algorithm,
- * the library provides functors for those operations. See the
- * documentation for @link functors the base classes@endlink
+ * The library provides function objects for basic arithmetic operations.
+ * See the documentation for @link functors function objects @endlink
* for examples of their use.
*
* @{
@@ -166,6 +179,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
template<typename _Tp>
struct plus : public binary_function<_Tp, _Tp, _Tp>
{
+ /// Returns the sum
_GLIBCXX14_CONSTEXPR
_Tp
operator()(const _Tp& __x, const _Tp& __y) const
@@ -319,7 +333,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 20.3.3 comparisons
/** @defgroup comparison_functors Comparison Classes
- * @ingroup functors
+ * @ingroup functors
*
* The library provides six wrapper functors for all the basic comparisons
* in C++, like @c <.
@@ -763,10 +777,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 20.3.4 logical operations
/** @defgroup logical_functors Boolean Operations Classes
- * @ingroup functors
+ * @ingroup functors
*
- * Here are wrapper functors for Boolean operations: @c &&, @c ||,
- * and @c !.
+ * The library provides function objects for the logical operations:
+ * `&&`, `||`, and `!`.
*
* @{
*/
@@ -971,30 +985,33 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 20.3.5 negators
/** @defgroup negators Negators
- * @ingroup functors
+ * @ingroup functors
*
- * The functions @c not1 and @c not2 each take a predicate functor
- * and return an instance of @c unary_negate or
- * @c binary_negate, respectively. These classes are functors whose
- * @c operator() performs the stored predicate function and then returns
- * the negation of the result.
+ * The function templates `not1` and `not2` are function object adaptors,
+ * which each take a predicate functor and wrap it in an instance of
+ * `unary_negate` or `binary_negate`, respectively. Those classes are
+ * functors whose `operator()` evaluates the wrapped predicate function
+ * and then returns the negation of the result.
*
* For example, given a vector of integers and a trivial predicate,
* \code
* struct IntGreaterThanThree
* : public std::unary_function<int, bool>
* {
- * bool operator() (int x) { return x > 3; }
+ * bool operator() (int x) const { return x > 3; }
* };
*
* std::find_if (v.begin(), v.end(), not1(IntGreaterThanThree()));
* \endcode
- * The call to @c find_if will locate the first index (i) of @c v for which
- * <code>!(v[i] > 3)</code> is true.
+ * The call to `find_if` will locate the first index (i) of `v` for which
+ * `!(v[i] > 3)` is true.
*
* The not1/unary_negate combination works on predicates taking a single
- * argument. The not2/binary_negate combination works on predicates which
- * take two arguments.
+ * argument. The not2/binary_negate combination works on predicates taking
+ * two arguments.
+ *
+ * @deprecated Deprecated in C++17, no longer in the standard since C++20.
+ * Use `not_fn` instead.
*
* @{
*/
@@ -1055,24 +1072,26 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 20.3.7 adaptors pointers functions
/** @defgroup pointer_adaptors Adaptors for pointers to functions
- * @ingroup functors
+ * @ingroup functors
*
* The advantage of function objects over pointers to functions is that
* the objects in the standard library declare nested typedefs describing
- * their argument and result types with uniform names (e.g., @c result_type
- * from the base classes @c unary_function and @c binary_function).
+ * their argument and result types with uniform names (e.g., `result_type`
+ * from the base classes `unary_function` and `binary_function`).
* Sometimes those typedefs are required, not just optional.
*
* Adaptors are provided to turn pointers to unary (single-argument) and
* binary (double-argument) functions into function objects. The
- * long-winded functor @c pointer_to_unary_function is constructed with a
- * function pointer @c f, and its @c operator() called with argument @c x
- * returns @c f(x). The functor @c pointer_to_binary_function does the same
- * thing, but with a double-argument @c f and @c operator().
+ * long-winded functor `pointer_to_unary_function` is constructed with a
+ * function pointer `f`, and its `operator()` called with argument `x`
+ * returns `f(x)`. The functor `pointer_to_binary_function` does the same
+ * thing, but with a double-argument `f` and `operator()`.
*
- * The function @c ptr_fun takes a pointer-to-function @c f and constructs
+ * The function `ptr_fun` takes a pointer-to-function `f` and constructs
* an instance of the appropriate functor.
*
+ * @deprecated Deprecated in C++11, no longer in the standard since C++17.
+ *
* @{
*/
/// One of the @link pointer_adaptors adaptors for function pointers@endlink.
@@ -1182,8 +1201,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
};
// 20.3.8 adaptors pointers members
- /** @defgroup memory_adaptors Adaptors for pointers to members
- * @ingroup functors
+ /** @defgroup ptrmem_adaptors Adaptors for pointers to members
+ * @ingroup functors
*
* There are a total of 8 = 2^3 function objects in this family.
* (1) Member functions taking no arguments vs member functions taking
@@ -1192,13 +1211,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* (3) Const vs non-const member function.
*
* All of this complexity is in the function objects themselves. You can
- * ignore it by using the helper function mem_fun and mem_fun_ref,
+ * ignore it by using the helper function `mem_fun` and `mem_fun_ref`,
* which create whichever type of adaptor is appropriate.
*
+ * @deprecated Deprecated in C++11, no longer in the standard since C++17.
+ * Use `mem_fn` instead.
+ *
* @{
*/
- /// One of the @link memory_adaptors adaptors for member
- /// pointers@endlink.
+ /// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp>
class mem_fun_t : public unary_function<_Tp*, _Ret>
{
@@ -1215,8 +1236,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)();
};
- /// One of the @link memory_adaptors adaptors for member
- /// pointers@endlink.
+ /// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp>
class const_mem_fun_t : public unary_function<const _Tp*, _Ret>
{
@@ -1233,8 +1253,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)() const;
};
- /// One of the @link memory_adaptors adaptors for member
- /// pointers@endlink.
+ /// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp>
class mem_fun_ref_t : public unary_function<_Tp, _Ret>
{
@@ -1251,8 +1270,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)();
};
- /// One of the @link memory_adaptors adaptors for member
- /// pointers@endlink.
+ /// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp>
class const_mem_fun_ref_t : public unary_function<_Tp, _Ret>
{
@@ -1269,8 +1287,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)() const;
};
- /// One of the @link memory_adaptors adaptors for member
- /// pointers@endlink.
+ /// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp, typename _Arg>
class mem_fun1_t : public binary_function<_Tp*, _Arg, _Ret>
{
@@ -1287,8 +1304,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)(_Arg);
};
- /// One of the @link memory_adaptors adaptors for member
- /// pointers@endlink.
+ /// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp, typename _Arg>
class const_mem_fun1_t : public binary_function<const _Tp*, _Arg, _Ret>
{
@@ -1305,8 +1321,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)(_Arg) const;
};
- /// One of the @link memory_adaptors adaptors for member
- /// pointers@endlink.
+ /// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp, typename _Arg>
class mem_fun1_ref_t : public binary_function<_Tp, _Arg, _Ret>
{
@@ -1323,8 +1338,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)(_Arg);
};
- /// One of the @link memory_adaptors adaptors for member
- /// pointers@endlink.
+ /// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp, typename _Arg>
class const_mem_fun1_ref_t : public binary_function<_Tp, _Arg, _Ret>
{
More information about the Libstdc++-cvs
mailing list