-
Notifications
You must be signed in to change notification settings - Fork 13.6k
Polishing documentation of libc++ #132962
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
martinlicht
commented
Mar 25, 2025
- Some lists re-ordered alphabetically
- numerous instances of spelling, grammar, language
Add _LIBCPP_REMOVE_TRANSITIVE_INCLUDES to the list of configuration macros
Co-authored-by: Louis Dionne <ldionne.2@gmail.com>
@llvm/pr-subscribers-libcxx Author: Martin Licht (martinlicht) Changes
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:
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]
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the patch. Overall, I believe this makes some things clearer, but I have some comments about a few places where IMO it doesn't.
Reflowing lines to a specific number of columns in our documentation has pretty low value IMO. I don't object to it in this patch since I've already reviewed the diff, but in the future please try to avoid mixing too many content changes with purely stylistic edits like line length, since that makes diffs harder to review.
Thanks!
libcxx/docs/UserDocumentation.rst
Outdated
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this rewording isn't much clearer. Perhaps this can be re-evaluated once the first sentence has been fixed?
libcxx/docs/UserDocumentation.rst
Outdated
This section documents various extensions to the C++ standard library | ||
provided by libc++ and any information regarding how to use them. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The old formulation was clearer. The new formulation reads as-if libc++ was "providing a C++ standard library".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't understand why you marked this comment as resolved but didn't make any changes.
Co-authored-by: Louis Dionne <ldionne.2@gmail.com>
Co-authored-by: Louis Dionne <ldionne.2@gmail.com>
Co-authored-by: Louis Dionne <ldionne.2@gmail.com>
Co-authored-by: Louis Dionne <ldionne.2@gmail.com>
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM w/ minor changes.
libcxx/docs/UserDocumentation.rst
Outdated
This section documents various extensions to the C++ standard library | ||
provided by libc++ and any information regarding how to use them. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't understand why you marked this comment as resolved but didn't make any changes.
LLVM Buildbot has detected a new failure on builder Full details are available at: https://lab.llvm.org/buildbot/#/builders/55/builds/11223 Here is the relevant piece of the build log for the reference
|