Automerge: [clang] Proofread LanguageExtensions.rst (#165082)

Author: kazutakahirata

clang/docs/LanguageExtensions.rst

@@ -32,7 +32,7 @@ Feature Checking Macros
 =======================
 
 Language extensions can be very useful, but only if you know you can depend on
-them.  In order to allow fine-grain features checks, we support three builtin
+them.  In order to allow fine-grained feature checks, we support three builtin
 function-like macros.  This allows you to directly test for a feature in your
 code without having to resort to something like autoconf or fragile "compiler
 version checks".
@@ -137,7 +137,7 @@ feature) or 0 if not.  They can be used like this:
 .. _langext-has-feature-back-compat:
 
 For backward compatibility, ``__has_feature`` can also be used to test
-for support for non-standardized features, i.e. features not prefixed ``c_``,
+for support for non-standardized features, i.e., features not prefixed ``c_``,
 ``cxx_`` or ``objc_``.
 
 Another use of ``__has_feature`` is to check for compiler features not related
@@ -159,7 +159,7 @@ of ``cxx_rvalue_references``.
 
 This function-like macro is available in C++20 by default, and is provided as an
 extension in earlier language standards. It takes a single argument that is the
-name of a double-square-bracket-style attribute. The argument can either be a
+name of a double-square-bracket-style attribute. The argument can be either a
 single identifier or a scoped identifier. If the attribute is supported, a
 nonzero value is returned. If the attribute is a standards-based attribute, this
 macro returns a nonzero value based on the year and month in which the attribute
@@ -320,7 +320,7 @@ To test for this feature, use ``#if defined(__has_include)``:
 
 .. code-block:: c++
 
-  // To avoid problem with non-clang compilers not having this macro.
+  // To avoid problems with non-clang compilers not having this macro.
   #if defined(__has_include)
   #if __has_include("myinclude.h")
   # include "myinclude.h"
@@ -345,7 +345,7 @@ or 0 otherwise:
   # include_next "myinclude.h"
   #endif
 
-  // To avoid problem with non-clang compilers not having this macro.
+  // To avoid problems with non-clang compilers not having this macro.
   #if defined(__has_include_next)
   #if __has_include_next("myinclude.h")
   # include_next "myinclude.h"
@@ -361,7 +361,7 @@ absolute path is used in the file argument.
 -----------------
 
 This function-like macro takes a string literal that represents a command line
-option for a warning and returns true if that is a valid warning option.
+option for a warning and returns ``true`` if that is a valid warning option.
 
 .. code-block:: c++
 
@@ -396,7 +396,7 @@ Builtin Macros
   file.
 
 ``__clang__``
-  Defined when compiling with Clang
+  Defined when compiling with Clang.
 
 ``__clang_major__``
   Defined to the major marketing version number of Clang (e.g., the 2 in
@@ -599,7 +599,7 @@ NEON vector types are created using ``neon_vector_type`` and
 
 GCC vector types are created using the ``vector_size(N)`` attribute.  The
 argument ``N`` specifies the number of bytes that will be allocated for an
-object of this type.  The size has to be multiple of the size of the vector
+object of this type.  The size has to be a multiple of the size of the vector
 element type. For example:
 
 .. code-block:: c++
@@ -620,7 +620,7 @@ element type. For example:
 Boolean Vectors
 ---------------
 
-Clang also supports the ext_vector_type attribute with boolean element types in
+Clang also supports the ``ext_vector_type`` attribute with boolean element types in
 C and C++.  For example:
 
 .. code-block:: c++
@@ -674,7 +674,7 @@ Vector Literals
 
 Vector literals can be used to create vectors from a set of scalars, or
 vectors.  Either parentheses or braces form can be used.  In the parentheses
-form the number of literal values specified must be one, i.e. referring to a
+form the number of literal values specified must be one, i.e., referring to a
 scalar value, or must match the size of the vector type being created.  If a
 single scalar literal value is specified, the scalar literal value will be
 replicated to all the components of the vector type.  In the brackets form any
@@ -725,12 +725,12 @@ address &v[i]                    no      no        no [#]_     no     no
 
 See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`.
 
-.. [#] ternary operator(?:) has different behaviors depending on condition
-  operand's vector type. If the condition is a GNU vector (i.e. __vector_size__),
+.. [#] ternary operator(?:) has different behaviors depending on the condition
+  operand's vector type. If the condition is a GNU vector (i.e., ``__vector_size__``),
   a NEON vector or an SVE vector, it's only available in C++ and uses normal bool
   conversions (that is, != 0).
   If it's an extension (OpenCL) vector, it's only available in C and OpenCL C.
-  And it selects based on signedness of the condition operands (OpenCL v1.1 s6.3.9).
+  And it selects based on the signedness of the condition operands (OpenCL v1.1 s6.3.9).
 .. [#] sizeof can only be used on vector length specific SVE types.
 .. [#] Clang does not allow the address of an element to be taken while GCC
    allows this. This is intentional for vectors with a boolean element type and
@@ -747,7 +747,7 @@ to perform additional operations on certain scalar and vector types.
 Let ``T`` be one of the following types:
 
 * an integer type (as in C23 6.2.5p22), but excluding enumerated types and ``bool``
-* the standard floating types float or double
+* the standard floating types ``float`` or ``double``
 * a half-precision floating point type, if one is supported on the target
 * a vector type.
 
@@ -833,7 +833,7 @@ of different sizes and signs is forbidden in binary and ternary builtins.
  T __builtin_elementwise_canonicalize(T x)      return the platform specific canonical encoding                        floating point types
                                                 of a floating-point number
  T __builtin_elementwise_copysign(T x, T y)     return the magnitude of x with the sign of y.                          floating point types
- T __builtin_elementwise_fmod(T x, T y)         return The floating-point remainder of (x/y) whose sign                floating point types
+ T __builtin_elementwise_fmod(T x, T y)         return the floating-point remainder of (x/y) whose sign                floating point types
                                                 matches the sign of x.
  T __builtin_elementwise_max(T x, T y)          return x or y, whichever is larger                                     integer and floating point types
                                                 For floating point types, follows semantics of maxNum
@@ -948,7 +948,7 @@ Let ``VT`` be a vector type and ``ET`` the element type of ``VT``.
 
 Each builtin accesses memory according to a provided boolean mask. These are
 provided as ``__builtin_masked_load`` and ``__builtin_masked_store``. The first
-argument is always boolean mask vector. The ``__builtin_masked_load`` builtin
+argument is always a boolean mask vector. The ``__builtin_masked_load`` builtin
 takes an optional third vector argument that will be used for the result of the
 masked-off lanes. These builtins assume the memory is unaligned, use
 ``__builtin_assume_aligned`` if alignment is desired.
@@ -1109,7 +1109,7 @@ to ``float``; see below for more information on this emulation.
 
 ``__fp16`` and ``_Float16`` both use the binary16 format from IEEE
 754-2008, which provides a 5-bit exponent and an 11-bit significand
-(counting the implicit leading 1). ``__bf16`` uses the `bfloat16
+(including the implicit leading 1). ``__bf16`` uses the `bfloat16
 <https://en.wikipedia.org/wiki/Bfloat16_floating-point_format>`_ format,
 which provides an 8-bit exponent and an 8-bit significand; this is the same
 exponent range as `float`, just with greatly reduced precision.
@@ -1143,7 +1143,7 @@ types with the ``-ffloat16-excess-precision=`` and
 
 * ``none``: meaning to perform strict operation-by-operation emulation
 * ``standard``: meaning that excess precision is permitted under the rules
-  described in the standard, i.e. never across explicit casts or statements
+  described in the standard, i.e., never across explicit casts or statements
 * ``fast``: meaning that excess precision is permitted whenever the
   optimizer sees an opportunity to avoid truncations; currently this has no
   effect beyond ``standard``
@@ -1899,7 +1899,7 @@ Type Trait Primitives
 
 Type trait primitives are special builtin constant expressions that can be used
 by the standard C++ library to facilitate or simplify the implementation of
-user-facing type traits in the <type_traits> header.
+user-facing type traits in the ``<type_traits>`` header.
 
 They are not intended to be used directly by user code because they are
 implementation-defined and subject to change -- as such they're tied closely to
@@ -2054,7 +2054,7 @@ The following type trait primitives are supported by Clang. Those traits marked
 * ``__is_volatile`` (C++, Embarcadero)
 * ``__reference_binds_to_temporary(T, U)`` (Clang):  Determines whether a
   reference of type ``T`` bound to an expression of type ``U`` would bind to a
-  materialized temporary object. If ``T`` is not a reference type the result
+  materialized temporary object. If ``T`` is not a reference type, the result
   is false. Note this trait will also return false when the initialization of
   ``T`` from ``U`` is ill-formed.
   Deprecated, use ``__reference_constructs_from_temporary``.
@@ -2182,7 +2182,7 @@ Prior to clang-16, the output may only be used safely when the indirect
 branches are not taken.  Query for this difference with
 ``__has_extension(gnu_asm_goto_with_outputs_full)``.
 
-When using tied-outputs (i.e. outputs that are inputs and outputs, not just
+When using tied-outputs (i.e., outputs that are inputs and outputs, not just
 outputs) with the `+r` constraint, there is a hidden input that's created
 before the label, so numeric references to operands must account for that.
 
@@ -2361,7 +2361,7 @@ Loading from a ``__weak`` variable always implicitly retains the
 loaded value.  In non-ARC modes, this retain is normally balanced
 by an implicit autorelease.  This autorelease can be suppressed
 by performing the load in the receiver position of a ``-retain``
-message send (e.g. ``[weakReference retain]``); note that this performs
+message send (e.g., ``[weakReference retain]``); note that this performs
 only a single retain (the retain done when primitively loading from
 the weak reference).
 
@@ -2562,7 +2562,7 @@ When a method that's introduced in the OS newer than the target OS is called, a
 .. code-block:: objc
 
   void my_fun(NSSomeClass* var) {
-    // If fancyNewMethod was added in e.g. macOS 10.12, but the code is
+    // If fancyNewMethod was added in e.g., macOS 10.12, but the code is
     // built with -mmacos-version-min=10.11, then this unconditional call
     // will emit a -Wunguarded-availability warning:
     [var fancyNewMethod];
@@ -2725,7 +2725,7 @@ correctly in any circumstances. It can be used if:
   metaprogramming algorithms to be able to specify/detect types generically.
 
 - the generated kernel binary does not contain indirect calls because they
-  are eliminated using compiler optimizations e.g. devirtualization.
+  are eliminated using compiler optimizations e.g., devirtualization.
 
 - the selected target supports the function pointer like functionality e.g.
   most CPU targets.
@@ -2755,12 +2755,12 @@ Extension Specification, section 1.2
 <https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#extensions-overview>`_.
 
 This is not conformant behavior and it can only be used portably when the
-functions with variadic prototypes do not get generated in binary e.g. the
+functions with variadic prototypes do not get generated in binary e.g., the
 variadic prototype is used to specify a function type with any number of
 arguments in metaprogramming algorithms in C++ for OpenCL.
 
 This extension can also be used when the kernel code is intended for targets
-supporting the variadic arguments e.g. majority of CPU targets.
+supporting the variadic arguments e.g., majority of CPU targets.
 
 **Example of Use**:
 
@@ -5170,8 +5170,8 @@ __builtin_amdgcn_fence
 
 ``__builtin_amdgcn_fence`` emits a fence.
 
-* ``unsigned`` atomic ordering, e.g. ``__ATOMIC_ACQUIRE``
-* ``const char *`` synchronization scope, e.g. ``workgroup``
+* ``unsigned`` atomic ordering, e.g., ``__ATOMIC_ACQUIRE``
+* ``const char *`` synchronization scope, e.g., ``workgroup``
 * Zero or more ``const char *`` address spaces names.
 
 The address spaces arguments must be one of the following string literals:
@@ -5205,7 +5205,7 @@ boolean argument as a bit for every lane of the current wave that is currently
 active (i.e., that is converged with the executing thread), and a 0 bit for
 every lane that is not active.
 
-The result is uniform, i.e. it is the same in every active thread of the wave.
+The result is uniform, i.e., it is the same in every active thread of the wave.
 
 __builtin_amdgcn_inverse_ballot_w{32,64}
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5374,7 +5374,7 @@ followed by ``off`` or ``on``.
 
 All function definitions in the region between an ``off`` and the following
 ``on`` will be decorated with the ``optnone`` attribute unless doing so would
-conflict with explicit attributes already present on the function (e.g. the
+conflict with explicit attributes already present on the function (e.g., the
 ones that control inlining).
 
 .. code-block:: c++
@@ -5472,12 +5472,12 @@ provides options for vectorization, interleaving, predication, unrolling and
 distribution. Loop hints can be specified before any loop and will be ignored if
 the optimization is not safe to apply.
 
-There are loop hints that control transformations (e.g. vectorization, loop
+There are loop hints that control transformations (e.g., vectorization, loop
 unrolling) and there are loop hints that set transformation options (e.g.
 ``vectorize_width``, ``unroll_count``).  Pragmas setting transformation options
-imply the transformation is enabled, as if it was enabled via the corresponding
-transformation pragma (e.g. ``vectorize(enable)``). If the transformation is
-disabled  (e.g. ``vectorize(disable)``), that takes precedence over
+imply the transformation is enabled, as if it were enabled via the corresponding
+transformation pragma (e.g., ``vectorize(enable)``). If the transformation is
+disabled  (e.g., ``vectorize(disable)``), that takes precedence over
 transformations option pragmas implying that transformation.
 
 Vectorization, Interleaving, and Predication
@@ -5704,7 +5704,7 @@ operation when supported by the target.
 The pragma can take three values: ``on``, ``fast`` and ``off``.  The ``on``
 option is identical to using ``#pragma STDC FP_CONTRACT(ON)`` and it allows
 fusion as specified the language standard.  The ``fast`` option allows fusion
-in cases when the language standard does not make this possible (e.g. across
+in cases when the language standard does not make this possible (e.g., across
 statements in C).
 
 .. code-block:: c++
@@ -5859,14 +5859,14 @@ and ``ignore_denormal_mode``, each optionally prefixed with ``no_``. The meaning
 are as follows:
 
 - ``remote_memory`` means atomic operations may be performed on remote
-  memory, i.e. memory accessed through off-chip interconnects (e.g., PCIe).
+  memory, i.e., memory accessed through off-chip interconnects (e.g., PCIe).
   On ROCm platforms using HIP, remote memory refers to memory accessed via
   PCIe and is subject to specific atomic operation support. See
   `ROCm PCIe Atomics <https://rocm.docs.amd.com/en/latest/conceptual/
   pcie-atomics.html>`_ for further details. Prefixing with ``no_remote_memory`` indicates that
   atomic operations should not be performed on remote memory.
 - ``fine_grained_memory`` means atomic operations may be performed on fine-grained
-  memory, i.e. memory regions that support fine-grained coherence, where updates to
+  memory, i.e., memory regions that support fine-grained coherence, where updates to
   memory are visible to other parts of the system even while modifications are ongoing.
   For example, in HIP, fine-grained coherence ensures that host and device share
   up-to-date data without explicit synchronization (see
@@ -6088,7 +6088,7 @@ match rules are specified after the attribute. The compiler expects an
 identifier that corresponds to the subject set specifier. The ``apply_to``
 specifier is currently the only supported subject set specifier. It allows you
 to specify match rules that form a subset of the attribute's allowed subject
-set, i.e. the compiler doesn't require all of the attribute's subjects. For
+set, i.e., the compiler doesn't require all of the attribute's subjects. For
 example, an attribute like ``[[nodiscard]]`` whose subject set includes
 ``enum``, ``record`` and ``hasType(functionType)``, requires the presence of at
 least one of these rules after ``apply_to``: