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.

1 files changed, 74 insertions, 60 deletions

diff --git a/libstdc++-v3/include/bits/stl_function.h b/libstdc++-v3/include/bits/stl_function.h
index 073018d..5de8c32 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>
     {