[clang] 799b6b9 - [clang][docs] Use `option` directive in User's Manual
KAWASHIMA Takahiro via cfe-commits
cfe-commits at lists.llvm.org
Mon Nov 21 17:42:55 PST 2022
Author: KAWASHIMA Takahiro
Date: 2022-11-22T10:40:54+09:00
New Revision: 799b6b9f3193bd8a4499da063dc7f74cfccadefd
URL: https://github.com/llvm/llvm-project/commit/799b6b9f3193bd8a4499da063dc7f74cfccadefd
DIFF: https://github.com/llvm/llvm-project/commit/799b6b9f3193bd8a4499da063dc7f74cfccadefd.diff
LOG: [clang][docs] Use `option` directive in User's Manual
Sphinx has the `option` directive. Most option descriptions
in `clang/docs/UsersManual.rst` used it but some didn't.
This commit changes the remaining option descriptions to use
the `option` directive. This makes a consistent view in HTML.
The `option` directive automatically creates a cross-reference target.
So labeling by `.. _opt_XXX:` is almost unnecessary. However, options
with and without `no-` (e.g. `-fno-show-column`/`-fshow-column`)
cannot be distinguish for the cross-reference. So some required
`.. _opt_XXX:` directives are kept unremoved.
Differential Revision: https://reviews.llvm.org/D138088
Added:
Modified:
clang/docs/OpenCLSupport.rst
clang/docs/UsersManual.rst
Removed:
################################################################################
diff --git a/clang/docs/OpenCLSupport.rst b/clang/docs/OpenCLSupport.rst
index 9372e63c0e62..8b68aa927116 100644
--- a/clang/docs/OpenCLSupport.rst
+++ b/clang/docs/OpenCLSupport.rst
@@ -34,7 +34,7 @@ Missing features or with limited support
list
<https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3Aopencl>`__.
-- Command-line flag :ref:`-cl-ext <opencl_cl_ext>` (used to override extensions/
+- Command-line flag :option:`-cl-ext` (used to override extensions/
features supported by a target) is missing support of some functionality i.e. that is
implemented fully through libraries (see :ref:`library-based features and
extensions <opencl_ext_libs>`).
@@ -235,7 +235,7 @@ Note that by default targets like `SPIR-V`, `SPIR` or `X86` expose all the OpenC
extensions. For all other targets the configuration has to be made explicitly.
Note that the target extension support performed by clang can be overridden
-with :ref:`-cl-ext <opencl_cl_ext>` command-line flags.
+with :option:`-cl-ext` command-line flags.
.. _opencl_ext_libs:
@@ -345,7 +345,7 @@ OpenCL C 3.0 Usage
OpenCL C 3.0 language standard makes most OpenCL C 2.0 features optional. Optional
functionality in OpenCL C 3.0 is indicated with the presence of feature-test macros
(list of feature-test macros is `here <https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_C.html#features>`__).
-Command-line flag :ref:`-cl-ext <opencl_cl_ext>` can be used to override features supported by a target.
+Command-line flag :option:`-cl-ext` can be used to override features supported by a target.
For cases when there is an associated extension for a specific feature (fp64 and 3d image writes)
user should specify both (extension and feature) in command-line flag:
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 69dcd495d689..dd4356d48f10 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -165,7 +165,8 @@ output format of the diagnostics that it generates.
.. _opt_fshow-column:
-**-f[no-]show-column**
+.. option:: -f[no-]show-column
+
Print column number in diagnostic.
This option, which defaults to on, controls whether or not Clang
@@ -187,7 +188,8 @@ output format of the diagnostics that it generates.
.. _opt_fshow-source-location:
-**-f[no-]show-source-location**
+.. option:: -f[no-]show-source-location
+
Print source file/line/column information in diagnostic.
This option, which defaults to on, controls whether or not Clang
@@ -206,7 +208,8 @@ output format of the diagnostics that it generates.
.. _opt_fcaret-diagnostics:
-**-f[no-]caret-diagnostics**
+.. option:: -f[no-]caret-diagnostics
+
Print source line and ranges from source code in diagnostic.
This option, which defaults to on, controls whether or not Clang
prints the source line, source ranges, and caret when emitting a
@@ -220,7 +223,8 @@ output format of the diagnostics that it generates.
^
//
-**-f[no-]color-diagnostics**
+.. option:: -f[no-]color-diagnostics
+
This option, which defaults to on when a color-capable terminal is
detected, controls whether or not Clang prints diagnostics in color.
@@ -247,7 +251,8 @@ output format of the diagnostics that it generates.
^
//
-**-fansi-escape-codes**
+.. option:: -fansi-escape-codes
+
Controls whether ANSI escape codes are used instead of the Windows Console
API to output colored diagnostics. This option is only used on Windows and
defaults to off.
@@ -277,7 +282,8 @@ output format of the diagnostics that it generates.
.. _opt_fdiagnostics-show-option:
-**-f[no-]diagnostics-show-option**
+.. option:: -f[no-]diagnostics-show-option
+
Enable ``[-Woption]`` information in diagnostic line.
This option, which defaults to on, controls whether or not Clang
@@ -293,13 +299,11 @@ output format of the diagnostics that it generates.
//
Passing **-fno-diagnostics-show-option** will prevent Clang from
- printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in
+ printing the [:option:`-Wextra-tokens`] information in
the diagnostic. This information tells you the flag needed to enable
or disable the diagnostic, either from the command line or through
:ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`.
-.. _opt_fdiagnostics-show-category:
-
.. option:: -fdiagnostics-show-category=none/id/name
Enable printing category information in diagnostic line.
@@ -347,7 +351,7 @@ output format of the diagnostics that it generates.
``-fsave-optimization-record=bitstream``: A binary format based on LLVM
Bitstream.
- The output file is controlled by :ref:`-foptimization-record-file <opt_foptimization-record-file>`.
+ The output file is controlled by :option:`-foptimization-record-file`.
In the absence of an explicit output file, the file is chosen using the
following scheme:
@@ -395,20 +399,18 @@ output format of the diagnostics that it generates.
``<base>-<arch>.opt.<format>``
Note that this is incompatible with passing the
- :ref:`-foptimization-record-file <opt_foptimization-record-file>` option.
+ :option:`-foptimization-record-file` option.
-.. _opt_foptimization-record-file:
+.. option:: -foptimization-record-file
-**-foptimization-record-file**
Control the file to which optimization reports are written. This implies
:ref:`-fsave-optimization-record <opt_fsave-optimization-record>`.
On Darwin platforms, this is incompatible with passing multiple
``-arch <arch>`` options.
-.. _opt_foptimization-record-passes:
+.. option:: -foptimization-record-passes
-**-foptimization-record-passes**
Only include passes which match a specified regular expression.
When optimization reports are being output (see
@@ -420,7 +422,8 @@ output format of the diagnostics that it generates.
.. _opt_fdiagnostics-show-hotness:
-**-f[no-]diagnostics-show-hotness**
+.. option:: -f[no-]diagnostics-show-hotness
+
Enable profile hotness information in diagnostic line.
This option controls whether Clang prints the profile hotness associated
@@ -443,9 +446,8 @@ output format of the diagnostics that it generates.
:ref:`-fsave-optimization-record <opt_fsave-optimization-record>` is used.
Otherwise, it defaults to off.
-.. _opt_fdiagnostics-hotness-threshold:
+.. option:: -fdiagnostics-hotness-threshold
-**-fdiagnostics-hotness-threshold**
Prevent optimization remarks from being output if they do not have at least
this hotness value.
@@ -458,7 +460,8 @@ output format of the diagnostics that it generates.
.. _opt_fdiagnostics-fixit-info:
-**-f[no-]diagnostics-fixit-info**
+.. option:: -f[no-]diagnostics-fixit-info
+
Enable "FixIt" information in the diagnostics output.
This option, which defaults to on, controls whether or not Clang
@@ -479,7 +482,8 @@ output format of the diagnostics that it generates.
.. _opt_fdiagnostics-print-source-range-info:
-**-fdiagnostics-print-source-range-info**
+.. option:: -fdiagnostics-print-source-range-info
+
Print machine parsable information about source ranges.
This option makes Clang print information about source ranges in a machine
parsable format after the file/line/column number information. The
@@ -577,8 +581,6 @@ Individual Warning Groups
TODO: Generate this from tblgen. Define one anchor per warning group.
-.. _opt_wextra-tokens:
-
.. option:: -Wextra-tokens
Warn about excess tokens at the end of a preprocessor directive.
@@ -1036,7 +1038,7 @@ the options that control it:
#. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
for clients that want to group diagnostics by class (for diagnostics
that support it)
- [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
+ [:option:`-fdiagnostics-show-category`].
#. The line of source code that the issue occurs on, along with a caret
and ranges that indicate the important locations
[:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
@@ -1073,7 +1075,7 @@ triage builds that produce a large number of errors or warnings in a
grouped way.
Categories are not shown by default, but they can be turned on with the
-:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option.
+:option:`-fdiagnostics-show-category` option.
When set to "``name``", the category is printed textually in the
diagnostic output. When it is set to "``id``", a category number is
printed. The mapping of category names to category id's can be obtained
@@ -1516,9 +1518,7 @@ floating point semantic models: precise (the default), strict, and fast.
Defaults to ``ieee``.
-.. _opt_fstrict-float-cast-overflow:
-
-**-f[no-]strict-float-cast-overflow**
+.. option:: -f[no-]strict-float-cast-overflow
When a floating-point value is not representable in a destination integer
type, the code has undefined behavior according to the language standard.
@@ -1526,9 +1526,7 @@ floating point semantic models: precise (the default), strict, and fast.
With the 'no-strict' option, Clang will saturate towards the smallest and
largest representable integer values instead. NaNs will be converted to zero.
-.. _opt_fmath-errno:
-
-**-f[no-]math-errno**
+.. option:: -f[no-]math-errno
Require math functions to indicate errors by setting errno.
The default varies by ToolChain. ``-fno-math-errno`` allows optimizations
@@ -1544,9 +1542,7 @@ floating point semantic models: precise (the default), strict, and fast.
``-fno-math-errno`` is the default. This includes most BSD-derived
systems, including Darwin.
-.. _opt_ftrapping-math:
-
-**-f[no-]trapping-math**
+.. option:: -f[no-]trapping-math
Control floating point exception behavior. ``-fno-trapping-math`` allows optimizations that assume that floating point operations cannot generate traps such as divide-by-zero, overflow and underflow.
@@ -1574,23 +1570,17 @@ floating point semantic models: precise (the default), strict, and fast.
* ``off`` (never fuse)
* ``fast-honor-pragmas`` (fuse across statements unless dictated by pragmas, default for HIP)
-.. _opt_fhonor-infinities:
-
-**-f[no-]honor-infinities**
+.. option:: -f[no-]honor-infinities
If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used,
has the same effect as specifying ``-ffinite-math-only``.
-.. _opt_fhonor-nans:
-
-**-f[no-]honor-nans**
+.. option:: -f[no-]honor-nans
If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used,
has the same effect as specifying ``-ffinite-math-only``.
-.. _opt_fapprox-func:
-
-**-f[no-]approx-func**
+.. option:: -f[no-]approx-func
Allow certain math function calls (such as ``log``, ``sqrt``, ``pow``, etc)
to be replaced with an approximately equivalent set of instructions
@@ -1599,32 +1589,24 @@ floating point semantic models: precise (the default), strict, and fast.
in cases where ``x`` is ``-0.0`` or ``-inf``.
Defaults to ``-fno-approx-func``.
-.. _opt_fsigned-zeros:
-
-**-f[no-]signed-zeros**
+.. option:: -f[no-]signed-zeros
Allow optimizations that ignore the sign of floating point zeros.
Defaults to ``-fno-signed-zeros``.
-.. _opt_fassociative-math:
-
-**-f[no-]associative-math**
+.. option:: -f[no-]associative-math
Allow floating point operations to be reassociated.
Defaults to ``-fno-associative-math``.
-.. _opt_freciprocal-math:
-
-**-f[no-]reciprocal-math**
+.. option:: -f[no-]reciprocal-math
Allow division operations to be transformed into multiplication by a
reciprocal. This can be significantly faster than an ordinary division
but can also have significantly less precision. Defaults to
``-fno-reciprocal-math``.
-.. _opt_funsafe-math-optimizations:
-
-**-f[no-]unsafe-math-optimizations**
+.. option:: -f[no-]unsafe-math-optimizations
Allow unsafe floating-point optimizations. Also implies:
@@ -1635,9 +1617,7 @@ floating point semantic models: precise (the default), strict, and fast.
Defaults to ``-fno-unsafe-math-optimizations``.
-.. _opt_ffinite-math-only:
-
-**-f[no-]finite-math-only**
+.. option:: -f[no-]finite-math-only
Allow floating-point optimizations that assume arguments and results are
not NaNs or +-Inf. This defines the ``__FINITE_MATH_ONLY__`` preprocessor macro.
@@ -1648,9 +1628,7 @@ floating point semantic models: precise (the default), strict, and fast.
Defaults to ``-fno-finite-math-only``.
-.. _opt_frounding-math:
-
-**-f[no-]rounding-math**
+.. option:: -f[no-]rounding-math
Force floating-point operations to honor the dynamically-set rounding mode by default.
@@ -1799,7 +1777,8 @@ Controlling Code Generation
Clang provides a number of ways to control code generation. The options
are listed below.
-**-f[no-]sanitize=check1,check2,...**
+.. option:: -f[no-]sanitize=check1,check2,...
+
Turn on runtime checks for various forms of undefined or suspicious
behavior.
@@ -1847,9 +1826,9 @@ are listed below.
``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same
program.
-**-f[no-]sanitize-recover=check1,check2,...**
+.. option:: -f[no-]sanitize-recover=check1,check2,...
-**-f[no-]sanitize-recover[=all]**
+.. option:: -f[no-]sanitize-recover[=all]
Controls which checks enabled by ``-fsanitize=`` flag are non-fatal.
If the check is fatal, program will halt after the first error
@@ -1873,9 +1852,9 @@ are listed below.
will have no effect on its own; it will need to be accompanied by
``-fno-sanitize-trap=alignment``.
-**-f[no-]sanitize-trap=check1,check2,...**
+.. option:: -f[no-]sanitize-trap=check1,check2,...
-**-f[no-]sanitize-trap[=all]**
+.. option:: -f[no-]sanitize-trap[=all]
Controls which checks enabled by the ``-fsanitize=`` flag trap. This
option is intended for use in cases where the sanitizer runtime cannot
@@ -1898,12 +1877,12 @@ are listed below.
Don't use ignorelist file, if it was specified earlier in the command line.
-**-f[no-]sanitize-coverage=[type,features,...]**
+.. option:: -f[no-]sanitize-coverage=[type,features,...]
Enable simple code coverage in addition to certain sanitizers.
See :doc:`SanitizerCoverage` for more details.
-**-f[no-]sanitize-address-outline-instrumentation**
+.. option:: -f[no-]sanitize-address-outline-instrumentation
Controls how address sanitizer code is generated. If enabled will always use
a function call instead of inlining the code. Turning this option on could
@@ -1911,7 +1890,7 @@ are listed below.
See :doc: `AddressSanitizer` for more details.
-**-f[no-]sanitize-stats**
+.. option:: -f[no-]sanitize-stats
Enable simple statistics gathering for the enabled sanitizers.
See :doc:`SanitizerStats` for more details.
@@ -2027,7 +2006,8 @@ are listed below.
compact branches and ``always`` generates compact branches whenever
possible.
-**-f[no-]max-type-align=[number]**
+.. option:: -f[no-]max-type-align=[number]
+
Instruct the code generator to not enforce a higher alignment than the given
number (of bytes) when accessing memory via an opaque pointer or reference.
This cap is ignored when directly accessing a variable or when the pointee
@@ -2068,7 +2048,7 @@ are listed below.
on ELF targets when using the integrated assembler. This flag currently
only has an effect on ELF targets.
-**-f[no]-unique-internal-linkage-names**
+.. option:: -f[no]-unique-internal-linkage-names
Controls whether Clang emits a unique (best-effort) symbol name for internal
linkage symbols. When this option is set, compiler hashes the main source
@@ -2089,7 +2069,7 @@ are listed below.
$ cd $P/bar && clang -c -funique-internal-linkage-names name_conflict.c
$ cd $P && clang foo/name_conflict.o && bar/name_conflict.o
-**-fbasic-block-sections=[labels, all, list=<arg>, none]**
+.. option:: -fbasic-block-sections=[labels, all, list=<arg>, none]
Controls how Clang emits text sections for basic blocks. With values ``all``
and ``list=<arg>``, each basic block or a subset of basic blocks can be placed
@@ -3295,8 +3275,6 @@ compiling for OpenCL, examples: ``-c``, ``-O<1-4|s>``, ``-o``, ``-emit-llvm``, e
Some extra options are available to support special OpenCL features.
-.. _opencl_cl_no_stdinc:
-
.. option:: -cl-no-stdinc
Allows to disable all extra types and functions that are not native to the compiler.
@@ -3416,7 +3394,7 @@ OpenCL Header
By default Clang will include standard headers and therefore most of OpenCL
builtin functions and types are available during compilation. The
default declarations of non-native compiler types and functions can be disabled
-by using flag :ref:`-cl-no-stdinc <opencl_cl_no_stdinc>`.
+by using flag :option:`-cl-no-stdinc`.
The following example demonstrates that OpenCL kernel sources with various
standard builtin functions can be compiled without the need for an explicit
More information about the cfe-commits
mailing list