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 --git a/libstdc++-v3/include/bits/stl_relops.h b/libstdc++-v3/include/bits/stl_relops.h
index 276894c..ef52203 100644 (file)
--- 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.
      */
 
     /**