[clang][docs] Correct floating point option explanations

[kawashima-fj]

Summary

Explanations for options of floating point are updated to match the RenderFloatingPointOptions function in clang/lib/Driver/ToolChains/Clang.cpp.

Missing explanations are also added.

[kawashima-fj]

I don't know it is inteded that -fno-fast-math does not imply -ftrapping-math and -frounding-math.
-ffast-math and -fno-fast-math is not symmetric in RenderFloatingPointOptions.

[zahiraam]

It would probably be better to make these changes with the appropriate code changes you are making for each semantic mode. And may be keep this patch only for the other changes you are proposing.

[zahiraam]

In D138117#3930423, @kawashima-fj wrote:

I don't know it is inteded that -fno-fast-math does not imply -ftrapping-math and -frounding-math.
-ffast-math and -fno-fast-math is not symmetric in RenderFloatingPointOptions.

I would think that there should be symmetry between ffast-math and fno-fast-math. Unless there is a good reason for it, in which case a comment should be added? @andrew.w.kaylor WDYT?

[kawashima-fj]

In D138117#3931109, @zahiraam wrote:

It would probably be better to make these changes with the appropriate code changes you are making for each semantic mode. And may be keep this patch only for the other changes you are proposing.

Sorry, I don't understand what you mean.
I didn't/won't change code (except a bug fix of D138109) or propose changing code.
I just want the document to be consistent with the existing code by this patch.
Are you saying about D138109? Or other things?

(Sorry, I'm not a native English speaker. My understanding may be bad.)

[zahiraam]

In D138117#3932688, @kawashima-fj wrote:

In D138117#3931109, @zahiraam wrote:

It would probably be better to make these changes with the appropriate code changes you are making for each semantic mode. And may be keep this patch only for the other changes you are proposing.

Sorry, I don't understand what you mean.
I didn't/won't change code (except a bug fix of D138109) or propose changing code.
I just want the document to be consistent with the existing code by this patch.
Are you saying about D138109? Or other things?

(Sorry, I'm not a native English speaker. My understanding may be bad.)

@@kawashima-fj no need to apologize!
What I meant was that the changes about the semantic mode approx-func that you made here https://reviews.llvm.org/D138109 , should have included the changes that you are making in this patch about approx-func.
In general, the changes to the users' manual should be in the same patch than the code changes.

[kawashima-fj]

In D138117#3933644, @zahiraam wrote:

What I meant was that the changes about the semantic mode approx-func that you made here https://reviews.llvm.org/D138109 , should have included the changes that you are making in this patch about approx-func.
In general, the changes to the users' manual should be in the same patch than the code changes.

Thanks. I understand.
Regarding D138109, the current manual already has the following sentences.

• precise Disables optimizations that are not value-safe on floating-point data, although FP contraction (FMA) is enabled (-ffp-contract=on). This is the default behavior.
• strict Enables -frounding-math and -ffp-exception-behavior=strict, and disables contractions (FMA). All of the -ffast-math enablements are disabled. Enables STDC FENV_ACCESS: by default FENV_ACCESS is disabled. This option setting behaves as though #pragma STDC FENV_ACESS ON appeared at the top of the source file.

These indicates that precise and strict should disable -fapprox-func. D138109 changes the code to be consistent with the manual.
So D138109 does not need to update the manual and this patch does not update the corresponding sentences.

[kawashima-fj]

ping

[zahiraam]

clang/docs/UsersManual.rst

1435

Leave a blank line before and after the bullet. Same below.

1612

-fno-signed-zeros. Same below.

1628

behave when combined.

1638

`-ffinite-math-only` implies:

[kawashima-fj]

Addressed to @zahiraam's comment

[zahiraam]

In D138117#3963560, @kawashima-fj wrote:

Addressed to @zahiraam's comment

Looks good.

clang/docs/UsersManual.rst

.. option:: -ffast-math
    macro. Some math libraries recognize this macro and change their behavior.
    With the exception of ``-ffp-contract=fast``, using any of the options
    below to disable any of the individual optimizations in ``-ffast-math``
    will cause ``__FAST_MATH__`` to no longer be set.
 
    This option implies:
 
    * ``-fno-honor-infinities``
-
    * ``-fno-honor-nans``
-
+   * ``-fapprox-func``
    * ``-fno-math-errno``
-
    * ``-ffinite-math-only``
-
    * ``-fassociative-math``
-
    * ``-freciprocal-math``
-
    * ``-fno-signed-zeros``
-
    * ``-fno-trapping-math``
-
+   * ``-fno-rounding-math``
    * ``-ffp-contract=fast``
 
    Note: ``-ffast-math`` causes ``crtfastmath.o`` to be linked with code. See
    :ref:`crtfastmath.o` for more details.
 
 .. option:: -fno-fast-math
 
    Disable fast-math mode.  This options disables unsafe floating-point
-   optimizations by preventing the compiler from making any tranformations that
+   optimizations by preventing the compiler from making any transformations that
    could affect the results.
 
    This option implies:
 
    * ``-fhonor-infinities``
-
    * ``-fhonor-nans``
-
-   * ``-fmath-errno``
-
+   * ``-fno-approx-func``
    * ``-fno-finite-math-only``
-
    * ``-fno-associative-math``
-
    * ``-fno-reciprocal-math``
-
    * ``-fsigned-zeros``
-
-   * ``-fno-trapping-math``
-
    * ``-ffp-contract=on``
 
-   * ``-fdenormal-fp-math=ieee``
+   Also, this option resets following options to their target-dependent defaults.
+
+   * ``-f[no-]math-errno``
+   * ``-fdenormal-fp-math=<value>``
 
    There is ambiguity about how ``-ffp-contract``, ``-ffast-math``,
    and ``-fno-fast-math`` behave in combination. To keep the value of
    ``-ffp-contract`` consistent, we define this set of rules:
 
    * ``-ffast-math`` sets ``ffp-contract`` to ``fast``.
 
    * ``-fno-fast-math`` sets ``-ffp-contract`` to ``on`` (``fast`` for CUDA and
.. option:: -fdenormal-fp-math=<value>
    Select which denormal numbers the code is permitted to require.
 
    Valid values are:
 
    * ``ieee`` - IEEE 754 denormal numbers
    * ``preserve-sign`` - the sign of a flushed-to-zero number is preserved in the sign of 0
    * ``positive-zero`` - denormals are flushed to positive zero
 
-   Defaults to ``ieee``.
+   The default value depends on the target. For most targets, defaults to
+   ``ieee``.
 
 .. 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.
    By default, Clang will not guarantee any particular result in that case.
    With the 'no-strict' option, Clang will saturate towards the smallest and
    largest representable integer values instead. NaNs will be converted to zero.
+   Defaults to ``-fstrict-float-cast-overflow``.
 
 .. option:: -f[no-]math-errno
 
    Require math functions to indicate errors by setting errno.
    The default varies by ToolChain.  ``-fno-math-errno`` allows optimizations
    that might cause standard C math functions to not set ``errno``.
    For example, on some systems, the math function ``sqrt`` is specified
    as setting ``errno`` to ``EDOM`` when the input is negative. On these
.. option:: -ffp-contract=<value>
 
    * ``fast`` (fuse across statements disregarding pragmas, default for CUDA)
    * ``on`` (fuse in the same statement unless dictated by pragmas, default for languages other than CUDA/HIP)
    * ``off`` (never fuse)
    * ``fast-honor-pragmas`` (fuse across statements unless dictated by pragmas, default for HIP)
 
 .. option:: -f[no-]honor-infinities
 
+   Allow floating-point optimizations that assume arguments and results are
+   not +-Inf.
+   Defaults to ``-fhonor-infinities``.
+
    If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used,
    has the same effect as specifying ``-ffinite-math-only``.
 
 .. option:: -f[no-]honor-nans
 
+   Allow floating-point optimizations that assume arguments and results are
+   not NaNs.
+   Defaults to ``-fhonor-nans``.
+
    If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used,
    has the same effect as specifying ``-ffinite-math-only``.
 
 .. 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
    or alternative math function calls. For example, a ``pow(x, 0.25)``
    may be replaced with ``sqrt(sqrt(x))``, despite being an inexact result
    in cases where ``x`` is ``-0.0`` or ``-inf``.
    Defaults to ``-fno-approx-func``.
 
 .. option:: -f[no-]signed-zeros
 
    Allow optimizations that ignore the sign of floating point zeros.
-   Defaults to ``-fno-signed-zeros``.
+   Defaults to ``-fsigned-zeros``.
 
 .. option:: -f[no-]associative-math
 
   Allow floating point operations to be reassociated.
   Defaults to ``-fno-associative-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``.
 
 .. option:: -f[no-]unsafe-math-optimizations
 
-   Allow unsafe floating-point optimizations. Also implies:
+   Allow unsafe floating-point optimizations.
+   ``-funsafe-math-optimizations`` also implies:
 
+   * ``-fapprox-func``
    * ``-fassociative-math``
    * ``-freciprocal-math``
    * ``-fno-signed-zeroes``
-   * ``-fno-trapping-math``.
+   * ``-fno-trapping-math``
+   * ``-ffp-contract=fast``
+
+   ``-fno-unsafe-math-optimizations`` implies:
+
+   * ``-fno-approx-func``
+   * ``-fno-associative-math``
+   * ``-fno-reciprocal-math``
+   * ``-fsigned-zeroes``
+   * ``-ftrapping-math``
+   * ``-ffp-contract=on``
+   * ``-fdenormal-fp-math=ieee``
+
+   There is ambiguity about how ``-ffp-contract``,
+   ``-funsafe-math-optimizations``, and ``-fno-unsafe-math-optimizations``
+   behave in combination. Explanation in :option:`-fno-fast-math` also applies
+   to these options.
 
    Defaults to ``-fno-unsafe-math-optimizations``.
 
 .. 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.
-   Also implies:
+   not NaNs or +-Inf. ``-ffinite-math-only`` defines the
+   ``__FINITE_MATH_ONLY__`` preprocessor macro.
+   ``-ffinite-math-only`` also implies:
 
    * ``-fno-honor-infinities``
    * ``-fno-honor-nans``
 
+   ``-ffno-inite-math-only`` implies:
+
+   * ``-fhonor-infinities``
+   * ``-fhonor-nans``
+
    Defaults to ``-fno-finite-math-only``.
 
 .. option:: -f[no-]rounding-math
 
    Force floating-point operations to honor the dynamically-set rounding mode by default.
 
    The result of a floating-point operation often cannot be exactly represented in the result type and therefore must be rounded.  IEEE 754 describes different rounding modes that control how to perform this rounding, not all of which are supported by all implementations.  C provides interfaces (``fesetround`` and ``fesetenv``) for dynamically controlling the rounding mode, and while it also recommends certain conventions for changing the rounding mode, these conventions are not typically enforced in the ABI.  Since the rounding mode changes the numerical result of operations, the compiler must understand something about it in order to optimize floating point operations.
 
.. option:: -ffp-eval-method=<value>
    ``double``; in the case of NETBSD greater than 6.99.26, with NoSSE, the
    default value is ``extended``, with SSE the default value is ``source``.
    Details:
 
    * ``source`` The compiler uses the floating-point type declared in the source program as the evaluation method.
    * ``double`` The compiler uses ``double`` as the floating-point evaluation method for all float expressions of type that is narrower than ``double``.
    * ``extended`` The compiler uses ``long double`` as the floating-point evaluation method for all float expressions of type that is narrower than ``long double``.
 
-.. option:: -f[no-]protect-parens:
+.. option:: -f[no-]protect-parens
 
    This option pertains to floating-point types, complex types with
    floating-point components, and vectors of these types. Some arithmetic
    expression transformations that are mathematically correct and permissible
    according to the C and C++ language standards may be incorrect when dealing
    with floating-point types, such as reassociation and distribution. Further,
    the optimizer may ignore parentheses when computing arithmetic expressions
    in circumstances where the parenthesized and unparenthesized expression
    express the same mathematical value. For example (a+b)+c is the same
    mathematical value as a+(b+c), but the optimizer is free to evaluate the
    additions in any order regardless of the parentheses. When enabled, this
    option forces the optimizer to honor the order of operations with respect
    to parentheses in all circumstances.
+   Defaults to ``-fno-protect-parens``.
 
    Note that floating-point contraction (option `-ffp-contract=`) is disabled
    when `-fprotect-parens` is enabled.  Also note that in safe floating-point
    modes, such as `-ffp-model=precise` or `-ffp-model=strict`, this option
    has no effect because the optimizer is prohibited from making unsafe
    transformations.
 
 .. _crtfastmath.o: