From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2181) id 8631B3857C74; Wed, 24 Nov 2021 11:50:52 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 8631B3857C74 MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="utf-8" From: Jonathan Wakely To: gcc-cvs@gcc.gnu.org, libstdc++-cvs@gcc.gnu.org Subject: [gcc r11-9284] libstdc++: Improve doxygen comments in X-Act-Checkin: gcc X-Git-Author: Jonathan Wakely X-Git-Refname: refs/heads/releases/gcc-11 X-Git-Oldrev: 22312ca1963ab8c938e9137ef8b217372e4b58f8 X-Git-Newrev: 6cd6b052400c30cf437b59b2d23808e13985b788 Message-Id: <20211124115052.8631B3857C74@sourceware.org> Date: Wed, 24 Nov 2021 11:50:52 +0000 (GMT) X-BeenThere: libstdc++-cvs@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libstdc++-cvs mailing list List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 24 Nov 2021 11:50:52 -0000 https://gcc.gnu.org/g:6cd6b052400c30cf437b59b2d23808e13985b788 commit r11-9284-g6cd6b052400c30cf437b59b2d23808e13985b788 Author: Jonathan Wakely Date: Wed Aug 18 12:18:35 2021 +0100 libstdc++: Improve doxygen comments in Add notes about deprecation and modern replacements. Fix bogus "memory_adaptors" group name. Use markdown for formatting. Signed-off-by: Jonathan Wakely libstdc++-v3/ChangeLog: * include/bits/stl_function.h: Improve doxygen comments. (cherry picked from commit 828176ba490d034d5d689f7733466530c25c5ed3) 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()); * \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()); * \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 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 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 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 * { - * 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 - * !(v[i] > 3) 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 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 class const_mem_fun_t : public unary_function { @@ -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 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 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 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 class const_mem_fun1_t : public binary_function { @@ -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 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 class const_mem_fun1_ref_t : public binary_function<_Tp, _Arg, _Ret> {