[libcxx-commits] [libcxx] Polishing documentation of libc++ (PR #132962)
Martin Licht via libcxx-commits
libcxx-commits at lists.llvm.org
Wed Mar 26 03:22:53 PDT 2025
https://github.com/martinlicht updated https://github.com/llvm/llvm-project/pull/132962
>From a705cfc897ae392e1d754e29d782914b2c04c592 Mon Sep 17 00:00:00 2001
From: Martin Licht <37779541+martinlicht at users.noreply.github.com>
Date: Mon, 10 Mar 2025 09:04:31 +0100
Subject: [PATCH 01/10] Update UserDocumentation.rst
Add _LIBCPP_REMOVE_TRANSITIVE_INCLUDES to the list of configuration macros
---
libcxx/docs/UserDocumentation.rst | 18 ++++++++++++++++++
1 file changed, 18 insertions(+)
diff --git a/libcxx/docs/UserDocumentation.rst b/libcxx/docs/UserDocumentation.rst
index 2c1bc1373659c..b55651a62ec5e 100644
--- a/libcxx/docs/UserDocumentation.rst
+++ b/libcxx/docs/UserDocumentation.rst
@@ -128,6 +128,24 @@ enable or disable extended libc++ behavior.
replacement scenarios from working, e.g. replacing `operator new` and
expecting a non-replaced `operator new[]` to call the replaced `operator new`.
+**_LIBCPP_REMOVE_TRANSITIVE_INCLUDES**:
+ When this macro is defined, the standard library headers will adhere to a
+ stricter policy regarding the (transitive) inclusion of other standard library
+ headers, only guaranteeing to provide those definitions explicitly mandated by
+ the standard. Please notice that defining this macro might break any existing
+ codebase that implicitly relies on standard headers providing any definitions
+ not explicitly required by the standard.
+
+ The primary motivation for this configuration macro is to improve compilation
+ times. In most standard library implementations, header files include more
+ definitions than officially required because the implementation details give rise
+ to internal dependencies. The common practice is to have the standard headers
+ internally include other standard headers, but this generally results in
+ increased compilation overhead. This configuration option attempts to mitigate
+ this problem by avoiding such unnecessary inclusions. In addition, compiling
+ a codebase with this macro may improve maintainability by identifying
+ missing standard header inclusions.
+
**_LIBCPP_DISABLE_DEPRECATION_WARNINGS**:
This macro disables warnings when using deprecated components. For example,
using `std::auto_ptr` when compiling in C++11 mode will normally trigger a
>From 2c9f0a9b9c8cbad805884c14fe4cc2a58ced3790 Mon Sep 17 00:00:00 2001
From: Louis Dionne <ldionne.2 at gmail.com>
Date: Wed, 19 Mar 2025 09:33:44 -0400
Subject: [PATCH 02/10] Minor rewording
---
libcxx/docs/UserDocumentation.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/libcxx/docs/UserDocumentation.rst b/libcxx/docs/UserDocumentation.rst
index b55651a62ec5e..469a26b90bee8 100644
--- a/libcxx/docs/UserDocumentation.rst
+++ b/libcxx/docs/UserDocumentation.rst
@@ -132,9 +132,9 @@ enable or disable extended libc++ behavior.
When this macro is defined, the standard library headers will adhere to a
stricter policy regarding the (transitive) inclusion of other standard library
headers, only guaranteeing to provide those definitions explicitly mandated by
- the standard. Please notice that defining this macro might break any existing
- codebase that implicitly relies on standard headers providing any definitions
- not explicitly required by the standard.
+ the standard. Please notice that defining this macro might break existing codebases
+ that implicitly rely on standard headers providing definitions not explicitly
+ required by the standard.
The primary motivation for this configuration macro is to improve compilation
times. In most standard library implementations, header files include more
>From bc876360742cd4547413f06bc269ea0c3b071386 Mon Sep 17 00:00:00 2001
From: Martin Licht <37779541+martinlicht at users.noreply.github.com>
Date: Wed, 19 Mar 2025 18:09:33 +0100
Subject: [PATCH 03/10] Update libcxx/docs/UserDocumentation.rst
Co-authored-by: Louis Dionne <ldionne.2 at gmail.com>
---
libcxx/docs/UserDocumentation.rst | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/libcxx/docs/UserDocumentation.rst b/libcxx/docs/UserDocumentation.rst
index 469a26b90bee8..4a11a10224ae9 100644
--- a/libcxx/docs/UserDocumentation.rst
+++ b/libcxx/docs/UserDocumentation.rst
@@ -142,10 +142,14 @@ enable or disable extended libc++ behavior.
to internal dependencies. The common practice is to have the standard headers
internally include other standard headers, but this generally results in
increased compilation overhead. This configuration option attempts to mitigate
- this problem by avoiding such unnecessary inclusions. In addition, compiling
- a codebase with this macro may improve maintainability by identifying
+ this problem by avoiding such unnecessary inclusions. Compiling
+ a codebase with this macro may improve portability by identifying
missing standard header inclusions.
+ However, be aware that enabling this macro may lead to breakages
+ when updating to a newer version of the library, since transitive includes
+ that your code was previously relying on may have been removed.
+
**_LIBCPP_DISABLE_DEPRECATION_WARNINGS**:
This macro disables warnings when using deprecated components. For example,
using `std::auto_ptr` when compiling in C++11 mode will normally trigger a
>From 0ceaf9a0b0e041055020c5b48e0b9299feaf8313 Mon Sep 17 00:00:00 2001
From: Martin Licht <martin.licht at epfl.ch>
Date: Tue, 25 Mar 2025 17:16:16 +0000
Subject: [PATCH 04/10] polishing the libc++ documentation
---
libcxx/docs/CodingGuidelines.rst | 12 +-
libcxx/docs/Hardening.rst | 16 +--
libcxx/docs/ImplementationDefinedBehavior.rst | 12 +-
libcxx/docs/Modules.rst | 2 +-
libcxx/docs/UserDocumentation.rst | 131 +++++++++---------
5 files changed, 87 insertions(+), 86 deletions(-)
diff --git a/libcxx/docs/CodingGuidelines.rst b/libcxx/docs/CodingGuidelines.rst
index 0c85cd07c0f61..50b3a9dc64895 100644
--- a/libcxx/docs/CodingGuidelines.rst
+++ b/libcxx/docs/CodingGuidelines.rst
@@ -79,9 +79,9 @@ and then check for ``#if _LIBCPP_SOMETHING_ENABLED`` instead of
and then checking for ``#ifdef _LIBCPP_SOMETHING_ENABLED``.
-This makes it significantly easier to catch missing includes, since Clang and GCC will warn when using and undefined
-marco inside an ``#if`` statement when using ``-Wundef``. Some macros in libc++ don't use this style yet, so this only
-applies when introducing a new macro.
+This makes it significantly easier to catch missing includes: Clang and GCC with ``-Wundef`` enabled will warn
+when using an undefined macro inside an ``#if`` statement. Some macros in libc++ don't use this style yet,
+so this guidelines only applies when introducing a new macro.
This is partially enforced by the clang-tidy check ``libcpp-internal-ftms``.
@@ -107,9 +107,9 @@ This is enforced by the clang-tidy check ``libcpp-uglify-attributes``.
Use C++11 extensions in C++03 code if they simplify the code
============================================================
-libc++ only supports Clang in C++98/03 mode. Clang provides many C++11 features in C++03, making it possible to write a
-lot of code in a simpler way than if we were restricted to C++03 features. Some use of extensions is even mandatory,
-since libc++ supports move semantics in C++03.
+libc++ supports the C++98/03 mode only with the Clang compiler. Clang provides many C++11 features
+in C++03, making it possible to write a lot of code in a simpler way than if we were restricted to C++03 features.
+Some use of extensions is even mandatory, since libc++ supports move semantics in C++03.
Use ``using`` aliases instead of ``typedef``
============================================
diff --git a/libcxx/docs/Hardening.rst b/libcxx/docs/Hardening.rst
index 097ad4b73b126..dc0322556023d 100644
--- a/libcxx/docs/Hardening.rst
+++ b/libcxx/docs/Hardening.rst
@@ -32,8 +32,8 @@ modes are:
including heuristic checks that might have significant performance overhead as
well as internal library assertions. This mode should be used in
non-production environments (such as test suites, CI, or local development).
- We don’t commit to a particular level of performance in this mode and it’s
- *not* intended to be used in production.
+ We do not commit to a particular level of performance in this mode.
+ In particular, this mode is *not* intended to be used in production.
.. note::
@@ -155,13 +155,13 @@ easier to reason about the high-level semantics of a hardening mode.
in the library -- whatever the consequences are, they will happen in the user
code.
-- ``pedantic`` -- checks preconditions that are imposed by the Standard, but
- violating which happens to be benign in libc++.
+- ``pedantic`` -- checks preconditions that are imposed by the C++ standard,
+ but violating which happens to be benign in libc++.
- ``semantic-requirement`` -- checks that the given argument satisfies the
- semantic requirements imposed by the Standard. Typically, there is no simple
- way to completely prove that a semantic requirement is satisfied; thus, this
- would often be a heuristic check and it might be quite expensive.
+ semantic requirements imposed by the C++ standard. Typically, there is no
+ simple way to completely prove that a semantic requirement is satisfied;
+ thus, this would often be a heuristic check and it might be quite expensive.
- ``internal`` -- checks that internal invariants of the library hold. These
assertions don't depend on user input.
@@ -239,7 +239,7 @@ Mapping between the hardening modes and the assertion categories
.. note::
- The categories enabled by each mode are subject to change and users should not
+ The categories enabled by each mode are subject to change: users should not
rely on the precise assertions enabled by a mode at a given point in time.
However, the library does guarantee to keep the hardening modes stable and
to fulfill the semantics documented here.
diff --git a/libcxx/docs/ImplementationDefinedBehavior.rst b/libcxx/docs/ImplementationDefinedBehavior.rst
index 1f95de77db0eb..153823fa0067e 100644
--- a/libcxx/docs/ImplementationDefinedBehavior.rst
+++ b/libcxx/docs/ImplementationDefinedBehavior.rst
@@ -4,8 +4,8 @@
Implementation-defined behavior
===============================
-Contains the implementation details of the implementation-defined behavior in
-libc++. Implementation-defined is mandated to be documented by the Standard.
+This page contains the implementation details of the implementation-defined behavior in libc++.
+The C++ standard mandates that implementation-defined behavior be documented.
.. note:
This page is far from complete.
@@ -17,7 +17,7 @@ Implementation-defined behavior
Updating the Time Zone Database
-------------------------------
-The Standard allows implementations to automatically update the
+The C++ standard allows implementations to automatically update the
*remote time zone database*. Libc++ opts not to do that. Instead calling
- ``std::chrono::remote_version()`` will update the version information of the
@@ -32,7 +32,7 @@ give them full control over the process.
`[ostream.formatted.print]/3 <http://eel.is/c++draft/ostream.formatted.print#3>`_ A terminal capable of displaying Unicode
--------------------------------------------------------------------------------------------------------------------------
-The Standard specifies that the manner in which a stream is determined to refer
+The C++ standard specifies that the manner in which a stream is determined to refer
to a terminal capable of displaying Unicode is implementation-defined. This is
used for ``std::print`` and similar functions taking an ``ostream&`` argument.
@@ -55,9 +55,9 @@ Libc++ determines that a stream is Unicode-capable terminal by:
----------------------------------------------------------------------------------------
Most functions within the Mathematical Special Functions section contain integral indices.
-The Standard specifies the result for larger indices as implementation-defined.
+The C++ standard specifies the result for larger indices as implementation-defined.
Libc++ pursuits reasonable results by choosing the same formulas as for indices below that threshold.
-E.g.
+E.g.,
- ``std::hermite(unsigned n, T x)`` for ``n >= 128``
diff --git a/libcxx/docs/Modules.rst b/libcxx/docs/Modules.rst
index 352a198f3774d..ebd851fed95fc 100644
--- a/libcxx/docs/Modules.rst
+++ b/libcxx/docs/Modules.rst
@@ -24,7 +24,7 @@ Overview
The module sources are stored in ``.cppm`` files. Modules need to be available
as BMIs, which are ``.pcm`` files for Clang. BMIs are not portable, they depend
-on the compiler used and its compilation flags. Therefore there needs to be a
+on the compiler and the compilation flags used. Therefore there needs to be a
way to distribute the ``.cppm`` files to the user and offer a way for them to
build and use the ``.pcm`` files. It is expected this will be done by build
systems in the future. To aid early adaptor and build system vendors libc++
diff --git a/libcxx/docs/UserDocumentation.rst b/libcxx/docs/UserDocumentation.rst
index 4a11a10224ae9..669a0d9a57048 100644
--- a/libcxx/docs/UserDocumentation.rst
+++ b/libcxx/docs/UserDocumentation.rst
@@ -7,29 +7,29 @@ User documentation
.. contents::
:local:
-This page contains information about configuration knobs that can be used by
-users when they know libc++ is used by their toolchain, and how to use libc++
-when it is not the default library used by their toolchain. It is aimed at
-users of libc++: a separate page contains documentation aimed at vendors who
-build and ship libc++ as part of their toolchain.
+This page contains information about for users of libc++:
+how to use libc++ if it is not the default library used by the toolchain,
+and what configuration knobs are available if libc++ is used by the toolchain.
+This page is aimed at users of libc++, whereas a separate page contains documentation
+aimed at vendors who build and ship libc++ as part of their toolchain.
Using a different version of the C++ Standard
=============================================
-Libc++ implements the various versions of the C++ Standard. Changing the version of
+Libc++ implements the various versions of the C++ standard. Changing the version of
the standard can be done by passing ``-std=c++XY`` to the compiler. Libc++ will
-automatically detect what Standard is being used and will provide functionality that
-matches that Standard in the library.
+automatically detect what standard is being used and will provide functionality that
+matches that standard in the library.
.. code-block:: bash
$ clang++ -std=c++17 test.cpp
-Note that using ``-std=c++XY`` with a version of the Standard that has not been ratified
+Note that using ``-std=c++XY`` with a version of the standard that has not been ratified
yet is considered unstable. While we strive to maintain stability, libc++ may be forced to
-make breaking changes to features shipped in a Standard that hasn't been ratified yet. Use
-these versions of the Standard at your own risk.
+make breaking changes to features shipped in a C++ standard that has not been ratified yet.
+Use these versions of the standard at your own risk.
Using libc++ when it is not the system default
@@ -39,16 +39,16 @@ Usually, libc++ is packaged and shipped by a vendor through some delivery vehicl
(operating system distribution, SDK, toolchain, etc) and users don't need to do
anything special in order to use the library.
-On systems where libc++ is provided but is not the default, Clang provides a flag
-called ``-stdlib=`` that can be used to decide which standard library is used.
+However, on systems where libc++ is provided but is not the default, we can envoke
+Clang with the flag ``-stdlib=`` to decide which standard library is used.
Using ``-stdlib=libc++`` will select libc++:
.. code-block:: bash
$ clang++ -stdlib=libc++ test.cpp
-On systems where libc++ is the library in use by default such as macOS and FreeBSD,
-this flag is not required.
+This flag is not required on systems where libc++ is the library in use by default,
+such as macOS and FreeBSD.
Enabling experimental C++ Library features
@@ -56,9 +56,9 @@ Enabling experimental C++ Library features
Libc++ provides implementations of some experimental features. Experimental features
are either Technical Specifications (TSes) or official features that were voted to
-the Standard but whose implementation is not complete or stable yet in libc++. Those
-are disabled by default because they are neither API nor ABI stable. However, the
-``-fexperimental-library`` compiler flag can be defined to turn those features on.
+the C++ standard but whose implementation is not complete or stable yet in libc++.
+Those are disabled by default because they are neither API nor ABI stable. However,
+users can define the ``-fexperimental-library`` compiler flag to turn those features on.
On compilers that do not support the ``-fexperimental-library`` flag (such as GCC),
users can define the ``_LIBCPP_ENABLE_EXPERIMENTAL`` macro and manually link against
@@ -75,7 +75,7 @@ when ``-fexperimental-library`` is passed:
.. note::
Experimental libraries are experimental.
* The contents of the ``<experimental/...>`` headers and the associated static
- library will not remain compatible between versions.
+ library will generally not remain compatible between versions.
* No guarantees of API or ABI stability are provided.
* When the standardized version of an experimental feature is implemented,
the experimental feature is removed two releases after the non-experimental
@@ -94,6 +94,24 @@ enable or disable extended libc++ behavior.
only intended to be used by vendors and changing their value from the one provided
in your toolchain can lead to unexpected behavior.
+**_LIBCPP_DISABLE_DEPRECATION_WARNINGS**:
+ This macro disables warnings when using deprecated components. For example,
+ using `std::auto_ptr` when compiling in C++11 mode will normally trigger a
+ warning saying that `std::auto_ptr` is deprecated. If the macro is defined,
+ no warning will be emitted. By default, this macro is not defined.
+
+**_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**:
+ This macro is used to disable all visibility annotations inside libc++.
+ Defining this macro and then building libc++ with hidden visibility gives a
+ build of libc++ which does not export any symbols, which can be useful when
+ building statically for inclusion into another library.
+
+**_LIBCPP_ENABLE_EXPERIMENTAL**:
+ This macro enables experimental features. This can be used on compilers that do
+ not support the ``-fexperimental-library`` flag. When used, users also need to
+ ensure that the appropriate experimental library (usually ``libc++experimental.a``)
+ is linked into their program.
+
**_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**:
This macro is used to enable -Wthread-safety annotations on libc++'s
``std::mutex`` and ``std::lock_guard``. By default, these annotations are
@@ -102,12 +120,6 @@ enable or disable extended libc++ behavior.
**_LIBCPP_HARDENING_MODE**:
This macro is used to choose the :ref:`hardening mode <using-hardening-modes>`.
-**_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**:
- This macro is used to disable all visibility annotations inside libc++.
- Defining this macro and then building libc++ with hidden visibility gives a
- build of libc++ which does not export any symbols, which can be useful when
- building statically for inclusion into another library.
-
**_LIBCPP_NO_VCRUNTIME**:
Microsoft's C and C++ headers are fairly entangled, and some of their C++
headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled
@@ -150,18 +162,6 @@ enable or disable extended libc++ behavior.
when updating to a newer version of the library, since transitive includes
that your code was previously relying on may have been removed.
-**_LIBCPP_DISABLE_DEPRECATION_WARNINGS**:
- This macro disables warnings when using deprecated components. For example,
- using `std::auto_ptr` when compiling in C++11 mode will normally trigger a
- warning saying that `std::auto_ptr` is deprecated. If the macro is defined,
- no warning will be emitted. By default, this macro is not defined.
-
-**_LIBCPP_ENABLE_EXPERIMENTAL**:
- This macro enables experimental features. This can be used on compilers that do
- not support the ``-fexperimental-library`` flag. When used, users also need to
- ensure that the appropriate experimental library (usually ``libc++experimental.a``)
- is linked into their program.
-
C++17 Specific Configuration Macros
-----------------------------------
**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**:
@@ -187,13 +187,6 @@ C++17 Specific Configuration Macros
C++20 Specific Configuration Macros
-----------------------------------
-**_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION**:
- This macro is used to re-enable `uncaught_exception`.
-
-**_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE**:
- This macro is used to re-enable the function
- ``std::shared_ptr<...>::unique()``.
-
**_LIBCPP_ENABLE_CXX20_REMOVED_BINDER_TYPEDEFS**:
This macro is used to re-enable the `argument_type`, `result_type`,
`first_argument_type`, and `second_argument_type` members of class
@@ -206,6 +199,10 @@ C++20 Specific Configuration Macros
**_LIBCPP_ENABLE_CXX20_REMOVED_RAW_STORAGE_ITERATOR**:
This macro is used to re-enable `raw_storage_iterator`.
+**_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE**:
+ This macro is used to re-enable the function
+ ``std::shared_ptr<...>::unique()``.
+
**_LIBCPP_ENABLE_CXX20_REMOVED_TEMPORARY_BUFFER**:
This macro is used to re-enable `get_temporary_buffer` and `return_temporary_buffer`.
@@ -213,10 +210,15 @@ C++20 Specific Configuration Macros
This macro is used to re-enable `is_literal_type`, `is_literal_type_v`,
`result_of` and `result_of_t`.
+**_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION**:
+ This macro is used to re-enable `uncaught_exception`.
C++26 Specific Configuration Macros
-----------------------------------
+**_LIBCPP_ENABLE_CXX26_REMOVED_ALLOCATOR_MEMBERS**:
+ This macro is used to re-enable redundant member of ``allocator<T>::is_always_equal``.
+
**_LIBCPP_ENABLE_CXX26_REMOVED_CODECVT**:
This macro is used to re-enable all named declarations in ``<codecvt>``.
@@ -224,9 +226,6 @@ C++26 Specific Configuration Macros
This macro is used to re-enable the function
``std::basic_string<...>::reserve()``.
-**_LIBCPP_ENABLE_CXX26_REMOVED_ALLOCATOR_MEMBERS**:
- This macro is used to re-enable redundant member of ``allocator<T>::is_always_equal``.
-
**_LIBCPP_ENABLE_CXX26_REMOVED_STRSTREAM**:
This macro is used to re-enable all named declarations in ``<strstream>``.
@@ -237,22 +236,22 @@ C++26 Specific Configuration Macros
Libc++ Extensions
=================
-This section documents various extensions provided by libc++, how they're
-provided, and any information regarding how to use them.
+This section documents various extensions to the C++ standard library
+provided by libc++ and any information regarding how to use them.
Extended integral type support
------------------------------
-Several platforms support types that are not specified in the Standard, such as
-the 128-bit integral types ``__int128_t`` and ``__uint128_t``. As an extension,
-libc++ does a best-effort attempt to support these types like other integral
-types, by supporting them notably in:
+Several platforms support types that are not specified in the C++ standard,
+such as the 128-bit integral types ``__int128_t`` and ``__uint128_t``.
+As an extension, libc++ does a best-effort attempt to support these types like
+other integral types, by supporting them notably in:
* ``<bits>``
* ``<charconv>``
* ``<functional>``
-* ``<type_traits>``
* ``<format>``
+* ``<type_traits>``
* ``<random>``
Additional types supported in random distributions
@@ -272,11 +271,10 @@ The exposition only type ``basic-format-string`` and its typedefs
``format_string``, and ``wformat_string`` in C++23. Libc++ makes these types
available in C++20 as an extension.
-For padding Unicode strings the ``format`` library relies on the Unicode
-Standard. Libc++ retroactively updates the Unicode Standard in older C++
-versions. This allows the library to have better estimates for newly introduced
-Unicode code points, without requiring the user to use the latest C++ version
-in their code base.
+For padding Unicode strings the ``format`` library relies on the Unicode standard.
+Libc++ retroactively updates the Unicode standard in older C++ versions.
+This allows the library to have better estimates for newly introduced Unicode code points,
+without requiring the user to use the latest C++ version in their code base.
In C++26 formatting pointers gained a type ``P`` and allows to use
zero-padding. These options have been retroactively applied to C++20.
@@ -297,8 +295,8 @@ pointer to heap-allocated memory, depending on the length of the string.
As of C++20, the constructors are now declared ``constexpr``, which permits strings to be used
during constant-evaluation time. In libc++, as in other common implementations, it is also possible
to constant-initialize a string object (e.g. via declaring a variable with ``constinit`` or
-``constexpr``), but, only if the string is short enough to not require a heap allocation. Reliance
-upon this should be discouraged in portable code, as the allowed length differs based on the
+``constexpr``), but only if the string is short enough to not require a heap allocation.
+Reliance upon this is discouraged in portable code, as the allowed length differs based on the
standard-library implementation and also based on whether the platform uses 32-bit or 64-bit
pointers.
@@ -317,12 +315,15 @@ Turning off ASan annotation in containers
-----------------------------------------
``__asan_annotate_container_with_allocator`` is a customization point to allow users to disable
-`Address Sanitizer annotations for containers <https://github.com/google/sanitizers/wiki/AddressSanitizerContainerOverflow>`_ for specific allocators. This may be necessary for allocators that access allocated memory.
+`Address Sanitizer annotations for containers <https://github.com/google/sanitizers/wiki/AddressSanitizerContainerOverflow>`_ for specific allocators.
+This may be necessary for allocators that access allocated memory.
This customization point exists only when ``_LIBCPP_HAS_ASAN_CONTAINER_ANNOTATIONS_FOR_ALL_ALLOCATORS`` Feature Test Macro is defined.
-For allocators not running destructors, it is also possible to `bulk-unpoison memory <https://github.com/google/sanitizers/wiki/AddressSanitizerManualPoisoning>`_ instead of disabling annotations altogether.
+For allocators not running destructors, it is also possible to `bulk-unpoison memory <https://github.com/google/sanitizers/wiki/AddressSanitizerManualPoisoning>`_
+instead of disabling annotations altogether.
-The struct may be specialized for user-defined allocators. It is a `Cpp17UnaryTypeTrait <http://eel.is/c++draft/type.traits#meta.rqmts>`_ with a base characteristic of ``true_type`` if the container is allowed to use annotations and ``false_type`` otherwise.
+The struct may be specialized for user-defined allocators. It is a `Cpp17UnaryTypeTrait <http://eel.is/c++draft/type.traits#meta.rqmts>`_
+with a base characteristic of ``true_type`` if the container is allowed to use annotations and ``false_type`` otherwise.
The annotations for a ``user_allocator`` can be disabled like this:
@@ -371,7 +372,7 @@ locale behave differently than they otherwise do. By default, wide character
streams don't convert wide characters but input/output them as is. If a
specific locale is imbued, the IO with the underlying stream happens with
regular ``char`` elements, which are converted to/from wide characters
-according to the locale. Note that this doesn't behave as expected if the
+according to the locale. Note that this will not behave as expected if the
stream has been set in Unicode mode.
>From 8fe72d5b616c07658e933dc2c8baf6b1862db248 Mon Sep 17 00:00:00 2001
From: Martin Licht <martin.licht at epfl.ch>
Date: Tue, 25 Mar 2025 23:30:09 +0100
Subject: [PATCH 05/10] Update libcxx/docs/CodingGuidelines.rst
Co-authored-by: Louis Dionne <ldionne.2 at gmail.com>
---
libcxx/docs/CodingGuidelines.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/libcxx/docs/CodingGuidelines.rst b/libcxx/docs/CodingGuidelines.rst
index 21c5dd78ae298..4a601dffa87ca 100644
--- a/libcxx/docs/CodingGuidelines.rst
+++ b/libcxx/docs/CodingGuidelines.rst
@@ -81,7 +81,7 @@ and then checking for ``#ifdef _LIBCPP_SOMETHING_ENABLED``.
This makes it significantly easier to catch missing includes: Clang and GCC with ``-Wundef`` enabled will warn
when using an undefined macro inside an ``#if`` statement. Some macros in libc++ don't use this style yet,
-so this guidelines only applies when introducing a new macro.
+so this guideline only applies when introducing a new macro.
This is partially enforced by the clang-tidy check ``libcpp-internal-ftms``.
>From c5579f49f6d1d11e59a1af3a7ebba73fed1ee3f8 Mon Sep 17 00:00:00 2001
From: Martin Licht <martin.licht at epfl.ch>
Date: Tue, 25 Mar 2025 23:30:48 +0100
Subject: [PATCH 06/10] Update libcxx/docs/UserDocumentation.rst
Co-authored-by: Louis Dionne <ldionne.2 at gmail.com>
---
libcxx/docs/UserDocumentation.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/libcxx/docs/UserDocumentation.rst b/libcxx/docs/UserDocumentation.rst
index 6c71511aa60df..86bfd6cb595e1 100644
--- a/libcxx/docs/UserDocumentation.rst
+++ b/libcxx/docs/UserDocumentation.rst
@@ -39,8 +39,8 @@ Usually, libc++ is packaged and shipped by a vendor through some delivery vehicl
(operating system distribution, SDK, toolchain, etc) and users don't need to do
anything special in order to use the library.
-However, on systems where libc++ is provided but is not the default, we can envoke
-Clang with the flag ``-stdlib=`` to decide which standard library is used.
+However, on systems where libc++ is provided but is not the default, Clang can be invoked
+with the ``-stdlib=`` flag to select which standard library is used.
Using ``-stdlib=libc++`` will select libc++:
.. code-block:: bash
>From 823a426868777d96c85795c2ca20d091b92b34e1 Mon Sep 17 00:00:00 2001
From: Martin Licht <martin.licht at epfl.ch>
Date: Tue, 25 Mar 2025 23:32:14 +0100
Subject: [PATCH 07/10] Update libcxx/docs/UserDocumentation.rst
Co-authored-by: Louis Dionne <ldionne.2 at gmail.com>
---
libcxx/docs/UserDocumentation.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/libcxx/docs/UserDocumentation.rst b/libcxx/docs/UserDocumentation.rst
index 86bfd6cb595e1..07b347076b4b5 100644
--- a/libcxx/docs/UserDocumentation.rst
+++ b/libcxx/docs/UserDocumentation.rst
@@ -58,7 +58,7 @@ Libc++ provides implementations of some experimental features. Experimental feat
are either Technical Specifications (TSes) or official features that were voted to
the C++ standard but whose implementation is not complete or stable yet in libc++.
Those are disabled by default because they are neither API nor ABI stable. However,
-users can define the ``-fexperimental-library`` compiler flag to turn those features on.
+users can use the ``-fexperimental-library`` compiler flag to turn those features on.
On compilers that do not support the ``-fexperimental-library`` flag (such as GCC),
users can define the ``_LIBCPP_ENABLE_EXPERIMENTAL`` macro and manually link against
>From fc4a71a96fa506ba53bc680fe8e7df74e4b3335d Mon Sep 17 00:00:00 2001
From: Martin Licht <martin.licht at epfl.ch>
Date: Tue, 25 Mar 2025 23:32:59 +0100
Subject: [PATCH 08/10] Update libcxx/docs/UserDocumentation.rst
Co-authored-by: Louis Dionne <ldionne.2 at gmail.com>
---
libcxx/docs/UserDocumentation.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/libcxx/docs/UserDocumentation.rst b/libcxx/docs/UserDocumentation.rst
index 07b347076b4b5..62d5e1b8f1964 100644
--- a/libcxx/docs/UserDocumentation.rst
+++ b/libcxx/docs/UserDocumentation.rst
@@ -144,7 +144,7 @@ enable or disable extended libc++ behavior.
When this macro is defined, the standard library headers will adhere to a
stricter policy regarding the (transitive) inclusion of other standard library
headers, only guaranteeing to provide those definitions explicitly mandated by
- the standard. Please notice that defining this macro might break existing codebasesgit
+ the standard. Please notice that defining this macro might break existing codebases
that implicitly rely on standard headers providing definitions not explicitly
required by the standard.
>From c515421012576a338d4953e86890479201a65803 Mon Sep 17 00:00:00 2001
From: Martin Licht <martin.licht at epfl.ch>
Date: Wed, 26 Mar 2025 11:22:07 +0100
Subject: [PATCH 09/10] Update libcxx/docs/Hardening.rst
Co-authored-by: Nikolas Klauser <nikolasklauser at berlin.de>
---
libcxx/docs/Hardening.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/libcxx/docs/Hardening.rst b/libcxx/docs/Hardening.rst
index dc0322556023d..17808841bd9ec 100644
--- a/libcxx/docs/Hardening.rst
+++ b/libcxx/docs/Hardening.rst
@@ -239,7 +239,7 @@ Mapping between the hardening modes and the assertion categories
.. note::
- The categories enabled by each mode are subject to change: users should not
+ The categories enabled by each mode are subject to change. Users should not
rely on the precise assertions enabled by a mode at a given point in time.
However, the library does guarantee to keep the hardening modes stable and
to fulfill the semantics documented here.
>From c71a9dcce1e66260b9e31045936f90689ae59abb Mon Sep 17 00:00:00 2001
From: Martin Licht <martin.licht at epfl.ch>
Date: Wed, 26 Mar 2025 11:22:41 +0100
Subject: [PATCH 10/10] Update libcxx/docs/ImplementationDefinedBehavior.rst
Co-authored-by: Nikolas Klauser <nikolasklauser at berlin.de>
---
libcxx/docs/ImplementationDefinedBehavior.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/libcxx/docs/ImplementationDefinedBehavior.rst b/libcxx/docs/ImplementationDefinedBehavior.rst
index 153823fa0067e..050451fc46a17 100644
--- a/libcxx/docs/ImplementationDefinedBehavior.rst
+++ b/libcxx/docs/ImplementationDefinedBehavior.rst
@@ -4,7 +4,7 @@
Implementation-defined behavior
===============================
-This page contains the implementation details of the implementation-defined behavior in libc++.
+This document contains the implementation details of the implementation-defined behavior in libc++.
The C++ standard mandates that implementation-defined behavior be documented.
.. note:
More information about the libcxx-commits
mailing list