[libcxx-commits] [libcxx] Polishing documentation of libc++ (PR #132962)
via libcxx-commits
libcxx-commits at lists.llvm.org
Tue Mar 25 10:36:14 PDT 2025
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-libcxx
Author: Martin Licht (martinlicht)
<details>
<summary>Changes</summary>
- Some lists re-ordered alphabetically
- numerous instances of spelling, grammar, language
---
Patch is 22.59 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/132962.diff
5 Files Affected:
- (modified) libcxx/docs/CodingGuidelines.rst (+6-6)
- (modified) libcxx/docs/Hardening.rst (+8-8)
- (modified) libcxx/docs/ImplementationDefinedBehavior.rst (+6-6)
- (modified) libcxx/docs/Modules.rst (+1-1)
- (modified) libcxx/docs/UserDocumentation.rst (+67-66)
``````````diff
diff --git a/libcxx/docs/CodingGuidelines.rst b/libcxx/docs/CodingGuidelines.rst
index c783a4f2e4e72..21c5dd78ae298 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..6c71511aa60df 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
@@ -132,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 codebases
+ the standard. Please notice that defining this macro might break existing codebasesgit
that implicitly rely on standard headers providing definitions not explicitly
required by the standard.
@@ -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 port...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/132962
More information about the libcxx-commits
mailing list