[libc++][doc] Update the release notes.

[Mordante]

Summary

I had a look at the changes since the last release and updated the
release notes with interesting changes.

It seems this time the release notes were already rather up to date :-)

If there are more interesting changes, please let me know and I'll
update the patch. I'd like to commit these changes latest next weekend
so they land before branching the 14.0 release.

I've added most active libc++ contributors. If I forgot anybody please add them.

[• Quuxplusone]

LGTM % comments!

libcxx/docs/ReleaseNotes.rst

41–47

56–59

65

@ChuanqiXu: Do you agree with this statement?
I don't specifically object to it myself, but I figure @ChuanqiXu is the person who knows best.

126–129

- The ``<experimental/coroutine>`` header is deprecated, as is any
  use of coroutines without C++20. Use C++20's ``<coroutine>`` header
  instead. The ``<experimental/coroutine>`` header will be removed
  in LLVM 15.

180–183

222–223

[ChuanqiXu]

libcxx/docs/ReleaseNotes.rst

65

Yeah, I agree. The <coroutine> header should already be completed.

[Mordante]

Thanks for the comments @Quuxplusone I'll address later with possible comments of others.

libcxx/docs/ReleaseNotes.rst

65

I based it on D109433 which marked the feature-test macro as implemented.

[ldionne]

LGTM, and I agree with pretty much all the suggested reformulations. I think it's great to see that we've collectively been getting much better at writing release notes as we make changes -- that's how it should be done.

[Mordante]

In D117948#3271005, @ldionne wrote:

LGTM, and I agree with pretty much all the suggested reformulations. I think it's great to see that we've collectively been getting much better at writing release notes as we make changes -- that's how it should be done.

Agreed and I too noticed the release notes were in a much better shape this time around.

Thanks for all review comments, especially @Quuxplusone for suggesting a lot of improvements.

libcxx/docs/ReleaseNotes.rst

41–47

This wording has changed in D115999, where you made similar suggestions which have been adopted.

libcxx/docs/ReleaseNotes.rst

 see the `releases page <https://llvm.org/releases/>`_.
 
 What's New in Libc++ 14.0.0?
 ============================
 
 New Features
 ------------
 
 - There's support for the C++20 header ``<format>``. Some parts are still
   missing, most notably the compile-time format string validation. Some
   functions are known to be inefficient, both in memory usage and performance.
   The implementation isn't API- or ABI-stable and therefore considered
   experimental. (Some not-yet-implemented papers require an API-break.)
   Vendors can still disable this header by turning the CMake option
   `LIBCXX_ENABLE_INCOMPLETE_FEATURES` off.
 
 - There's a new CMake option ``LIBCXX_ENABLE_UNICODE`` to disable Unicode
   support in the ``<format>`` header. This only affects the estimation of the
   output width of the format functions.
 
 - Support for building libc++ on top of a C Standard Library that does not support ``wchar_t`` was
   added. This is useful for building libc++ in an embedded setting, and it adds itself to the various
   freestanding-friendly options provided by libc++.
 
-- ``_LIBCPP_DEBUG`` equals to ``1`` enables the randomization of unspecified
-  behavior of standard algorithms (e.g. equal elements in ``std::sort`` or
-  randomization of both sides of partition for ``std::nth_element``)
+- Defining ``_LIBCPP_DEBUG`` to ``1`` enables the randomization of unspecified
+  behavior in standard algorithms (e.g. the ordering of equal elements in ``std::sort``, or
+  the ordering of both sides of the partition in ``std::nth_element``).
 
 - Floating-point support for ``std::to_chars`` support has been added.
   Thanks to Stephan T. Lavavej and Microsoft for providing their implementation
   to libc++.
 
+- The C++20 ``<coroutine>`` implementation has been completed.
+
+- More C++20 features have been implemented. :doc:`Status/Cxx20` has the full
+  overview of libc++'s C++20 implementation status.
+
+- More C++2b features have been implemented. :doc:`Status/Cxx2b` has the full
+  overview of libc++'s C++2b implementation status.
+
 API Changes
 -----------
 
 - The functions ``std::atomic<T*>::fetch_(add|sub)`` and
   ``std::atomic_fetch_(add|sub)`` no longer accept a function pointer. While
   this is technically an API break, the invalid syntax isn't supported by
   libstdc++ and MSVC STL.  See https://godbolt.org/z/49fvzz98d.
 
- ``std::filesystem::path::iterator``, which (in our implementation) stashes
   After this change, ``for`` loops of the form ``for (auto& c : path)`` must be rewritten
   as either ``for (auto&& c : path)`` or ``for (const auto& c : path)``.
   ``std::reverse_iterator<path::iterator>`` is no longer rejected.
 
 - Removed the nonstandard default constructor from ``std::chrono::month_weekday``.
   You must now explicitly initialize with a ``chrono::month`` and
   ``chrono::weekday_indexed`` instead of "meh, whenever".
 
 - C++20 requires that ``std::basic_string::reserve(n)`` never reduce the capacity
   of the string. (For that, use ``shrink_to_fit()``.) Prior to this release, libc++'s
   ``std::basic_string::reserve(n)`` could reduce capacity in C++17 and before, but
   not in C++20 and later. This caused ODR violations when mixing code compiled under
   different Standard modes. After this change, libc++'s ``std::basic_string::reserve(n)``
   never reduces capacity, even in C++17 and before.
   C++20 deprecates the zero-argument overload of ``std::basic_string::reserve()``,
   but specifically permits it to reduce capacity. To avoid breaking existing code
   assuming that ``std::basic_string::reserve()`` will shrink, libc++ maintains
   the behavior to shrink, even though that makes ``std::basic_string::reserve()`` not
   a synonym for ``std::basic_string::reserve(0)`` in any Standard mode anymore.
 
+- The ``<experimental/coroutine>`` header is deprecated, as is any
+  use of coroutines without C++20. Use C++20's ``<coroutine>`` header
+  instead. The ``<experimental/coroutine>`` header will be removed
+  in LLVM 15.
+
 ABI Changes
 -----------
 
 - The C++17 variable templates ``is_error_code_enum_v`` and
   ``is_error_condition_enum_v`` are now of type ``bool`` instead of ``size_t``.
 
 - The C++03 emulation type for ``std::nullptr_t`` has been removed in favor of
   using ``decltype(nullptr)`` in all standard modes. This is an ABI break for
- ``std::lognormal_distribution::param_type`` used to store a data member of type
   define the macro.
 
 Build System Changes
 --------------------
 
 - Building the libc++ shared or static library requires a C++ 20 capable compiler.
   Consider using a Bootstrapping build to build libc++ with a fresh Clang if you
   can't use the system compiler to build libc++ anymore.
 
-- Historically, there has been numerous ways of building libc++ and libc++abi. This has
-  culminated in over 5 different ways to build the runtimes, which made it impossible to
-  maintain with a good level of support. Starting with this release, the runtimes support
+- Historically, there have been numerous ways of building libc++ and libc++abi. This has
+  led to at least 5 different ways to build the runtimes, which was impossible to
+  maintain with a good level of support. Starting with this release, libc++ and libc++abi support
   exactly two ways of being built, which should cater to all use-cases. Furthermore,
   these builds are as lightweight as possible and will work consistently even when targeting
-  embedded platforms, which used not to be the case. Please see the documentation on building
-  libc++ to see those two ways of building and migrate over to the appropriate build instructions
+  embedded platforms, which used not to be the case. :doc:`BuildingLibcxx` describes
+  those two ways of building. Please migrate over to the appropriate build instructions
   as soon as possible.
 
   All other ways to build are deprecated and will not be supported in the next release.
   We understand that making these changes can be daunting. For that reason, here's a
   summary of how to migrate from the two most common ways to build:
 
   - If you were rooting your CMake invocation at ``<monorepo>/llvm`` and passing ``-DLLVM_ENABLE_PROJECTS=<...>``
     (which was the previously advertised way to build the runtimes), please simply root your CMake invocation at
- Support for building the runtimes using the GCC 32 bit multilib flag (``-m32``) has been removed. Support
   for this had been flaky for a while, and we didn't know of anyone depending on this. Instead, please perform
   a normal cross-compilation of the runtimes using the appropriate target, such as passing the following to
   your bootstrapping build:
 
   .. code-block:: bash
 
       -DLLVM_RUNTIME_TARGETS=i386-unknown-linux
 
-- Libc++, libc++abi and libunwind will not be built with ``-fPIC`` by default anymore.
-  If you want to build those runtimes with position independent code, please specify
+- Libc++, libc++abi, and libunwind will not be built with ``-fPIC`` by default anymore.
+  If you want to build those runtimes with position-independent code, please specify
   ``-DCMAKE_POSITION_INDEPENDENT_CODE=ON`` explicitly when configuring the build, or
   ``-DRUNTIMES_<target-name>_CMAKE_POSITION_INDEPENDENT_CODE=ON`` if using the
   bootstrapping build.