caio/clang-p2996
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[libc++] Documentation polish (#132962)

Browse Source 
- Some lists re-ordered alphabetically
- Spelling, grammar, language, etc
This commit is contained in:
Martin Licht
2025-05-12 22:23:31 +02:00
committed by GitHub
parent fc3b67aee8
commit 608c85cb02
5 changed files with 87 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
libcxx/docs/CodingGuidelines.rst
View File

@@ -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 guideline 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``
============================================

16
libcxx/docs/Hardening.rst
View File

@@ -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.

12
libcxx/docs/ImplementationDefinedBehavior.rst
View File

@@ -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 document contains the implementation details of the implementation-defined behavior in libc++.
The C++ standard mandates that implementation-defined behavior is 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``

2
libcxx/docs/Modules.rst
View File

@@ -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++

131
libcxx/docs/UserDocumentation.rst
View File

@@ -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 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, Clang can be invoked
with the ``-stdlib=`` flag to select 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 default standard library,
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 enable 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 may 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,23 +236,23 @@ 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 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>``
* ``<random>``
* ``<type_traits>``
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.