[gcc r12-2485] libstdc++: Update documentation comments for namespace rel_ops

[gcc r12-2485] libstdc++: Update documentation comments for namespace rel_ops

[Jonathan Wakely]

https://gcc.gnu.org/g:5b965dc49a6a4293ce85bc3a24ca3f3855469e68

commit r12-2485-g5b965dc49a6a4293ce85bc3a24ca3f3855469e68
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Fri Jul 23 11:03:23 2021 +0100

    libstdc++: Update documentation comments for namespace rel_ops
    
    The comments in <bits/stl_relops.h> describe problems that were solved
    years ago (for GCC 3.1). The comparison operators in <iterator> are no
    longer ambiguous with the rel_ops ones, so the linked mailing list
    thread and FAQ entry aren't relevant now. The reference to std_utility.h
    is also outdated as it's just called utility now, both in the source
    tree and when installed.
    
    The use of rel_ops is still frowned upon though, so replace the
    discussion of ambiguities within libstdc++ headers with adminition about
    using rel_ops in user code.
    
    Signed-off-by: Jonathan Wakely <jwakely@redhat.com>
    
    libstdc++-v3/ChangeLog:
    
            * include/bits/stl_relops.h: Update documentation comments.

Diff:
---
 libstdc++-v3/include/bits/stl_relops.h | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/libstdc++-v3/include/bits/stl_relops.h b/libstdc++-v3/include/bits/stl_relops.h
index 276894c435a..ef522031318 100644
--- a/libstdc++-v3/include/bits/stl_relops.h
+++ b/libstdc++-v3/include/bits/stl_relops.h
@@ -52,13 +52,8 @@
  *  This is an internal header file, included by other library headers.
  *  Do not attempt to use it directly. @headername{utility}
  *
- *  Inclusion of this file has been removed from
- *  all of the other STL headers for safety reasons, except std_utility.h.
- *  For more information, see the thread of about twenty messages starting
- *  with http://gcc.gnu.org/ml/libstdc++/2001-01/msg00223.html, or
- *  http://gcc.gnu.org/onlinedocs/libstdc++/faq.html#faq.ambiguous_overloads
- *
- *  Short summary: the rel_ops operators should be avoided for the present.
+ *  This file is only included by `<utility>`, which is required by the
+ *  standard to define namespace `rel_ops` and its contents.
  */
 
 #ifndef _STL_RELOPS_H
@@ -72,6 +67,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   {
     /** @namespace std::rel_ops
      *  @brief  The generated relational operators are sequestered here.
+     *
+     *  Libstdc++ headers must not use the contents of `rel_ops`.
+     *  User code should also avoid them, because unconstrained function
+     *  templates are too greedy and can easily cause ambiguities.
+     *
+     *  C++20 default comparisons are a better solution.
      */
 
     /**