kawashima-fj created this revision.
kawashima-fj added a project: clang.
Herald added a project: All.
kawashima-fj requested review of this revision.
Herald added a subscriber: cfe-commits.
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.
Repository:
rG LLVM Github Monorepo
https://reviews.llvm.org/D138088
Files:
clang/docs/OpenCLSupport.rst
clang/docs/UsersManual.rst
Index: clang/docs/UsersManual.rst
===================================================================
--- clang/docs/UsersManual.rst
+++ clang/docs/UsersManual.rst
@@ -165,7 +165,8 @@
.. _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 @@
.. _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 @@
.. _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 @@
^
//
-**-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 @@
^
//
-**-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 @@
.. _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 @@
//
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 @@
``-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 @@
``<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 @@
.. _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 @@
: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 @@
.. _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 @@
.. _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 @@
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.
@@ -1033,7 +1035,7 @@
#. 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>`].
@@ -1070,7 +1072,7 @@
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
@@ -1513,9 +1515,7 @@
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.
@@ -1523,9 +1523,7 @@
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
@@ -1541,9 +1539,7 @@
``-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.
@@ -1571,23 +1567,17 @@
* ``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
@@ -1596,32 +1586,24 @@
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:
@@ -1632,9 +1614,7 @@
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.
@@ -1645,9 +1625,7 @@
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.
@@ -1796,7 +1774,8 @@
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.
@@ -1844,9 +1823,9 @@
``-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
@@ -1870,9 +1849,9 @@
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
@@ -1895,12 +1874,12 @@
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
@@ -1908,7 +1887,7 @@
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.
@@ -2024,7 +2003,8 @@
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
@@ -2065,7 +2045,7 @@
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
@@ -2086,7 +2066,7 @@
$ 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
@@ -3292,8 +3272,6 @@
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.
@@ -3413,7 +3391,7 @@
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
Index: clang/docs/OpenCLSupport.rst
===================================================================
--- clang/docs/OpenCLSupport.rst
+++ clang/docs/OpenCLSupport.rst
@@ -34,7 +34,7 @@
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 @@
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 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:
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
