[gcc r12-5685] d: Update documentation of new D language options.

[Iain Buclaw <ibuclaw@gcc.gnu.org>]

https://gcc.gnu.org/g:47fe7be66e18a154ace54a9c98366e9e023e9dd3

commit r12-5685-g47fe7be66e18a154ace54a9c98366e9e023e9dd3
Author: Iain Buclaw <ibuclaw@gdcproject.org>
Date:   Wed Dec 1 11:46:46 2021 +0100

    d: Update documentation of new D language options.
    
    Adds documentation for the following:
    
        - New switch that controls what code is generated on a contract
          failure (throw or abort).
        - New switch that controls mangling of D types in `extern(C++)`
          code, as well as setting the compile-time value of
          `__traits(getTargetInfo "cppStd")`
        - New switches that generate C++ headers from D source files.
        - New switch to save expanded mixins to a file.
        - New switches that now distinguish between D language changes that
          are either (a) an experimental feature or an upcoming breaking
          change, (b) a warning or help on an upcoming change, or (c) revert
          of a change for users who don't want to deal with the breaking
          change for now.
    
    gcc/d/ChangeLog:
    
            * gdc.texi (Runtime Options): Document -fcheckaction=, -fextern-std=,
            -fpreview=, -frevert=.
            (Code Generation): Document -fdump-c++-spec=, -fdump-c++-spec-verbose,
            -fsave-mixins=.
            (Warnings): Update list of supported -ftransitions=.

Diff:
---
 gcc/d/gdc.texi | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 109 insertions(+), 5 deletions(-)

diff --git a/gcc/d/gdc.texi b/gcc/d/gdc.texi
index 095f7ecca41..c98eb1f45d9 100644
--- a/gcc/d/gdc.texi
+++ b/gcc/d/gdc.texi
@@ -216,6 +216,20 @@ Don't recognize built-in functions unless they begin with the prefix
 @samp{__builtin_}.  By default, the compiler will recognize when a
 function in the @code{core.stdc} package is a built-in function.
 
+@item -fcheckaction=@var{value}
+@cindex @option{-fcheckaction}
+This option controls what code is generated on an assertion, bounds check, or
+final switch failure.  The following values are supported:
+
+@table @samp
+@item context
+Throw an @code{AssertError} with extra context information.
+@item halt
+Halt the program execution.
+@item throw
+Throw an @code{AssertError} (the default).
+@end table
+
 @item -fdebug
 @item -fdebug=@var{value}
 @cindex @option{-fdebug}
@@ -245,6 +259,25 @@ This is equivalent to compiling with the following options:
 gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti
 @end example
 
+@item -fextern-std=@var{standard}
+@cindex @option{-fextern-std}
+Sets the C++ name mangling compatibility to the version identified by
+@var{standard}.  The following values are supported:
+
+@table @samp
+@item c++98
+@item c++03
+Sets @code{__traits(getTargetInfo "cppStd")} to @code{199711}.
+@item c++11
+Sets @code{__traits(getTargetInfo "cppStd")} to @code{201103}.
+@item c++14
+Sets @code{__traits(getTargetInfo "cppStd")} to @code{201402}.
+@item c++17
+Sets @code{__traits(getTargetInfo "cppStd")} to @code{201703}.
+@item c++20
+Sets @code{__traits(getTargetInfo "cppStd")} to @code{202002}.
+@end table
+
 @item -fno-invariants
 @cindex @option{-finvariants}
 @cindex @option{-fno-invariants}
@@ -276,6 +309,48 @@ Turns off code generation for postcondition @code{out} contracts.
 @cindex @option{-fno-preconditions}
 Turns off code generation for precondition @code{in} contracts.
 
+@item -fpreview=@var{id}
+@cindex @option{-fpreview}
+Turns on an upcoming D language change identified by @var{id}.  The following
+values are supported:
+
+@table @samp
+@item all
+Turns on all upcoming D language features.
+@item dip1000
+Implements @uref{http://wiki.dlang.org/DIP1000} (Scoped pointers).
+@item dip1008
+Implements @uref{http://wiki.dlang.org/DIP1008} (Allow exceptions in
+@code{@@nogc} code).
+@item dip1021
+Implements @uref{http://wiki.dlang.org/DIP1021} (Mutable function arguments).
+@item dip25
+Implements @uref{http://wiki.dlang.org/DIP25} (Sealed references).
+@item dtorfields
+Turns on generation for destructing fields of partially constructed objects.
+@item fieldwise
+Turns on generation of struct equality to use field-wise comparisons.
+@item fixaliasthis
+Implements new lookup rules that check the current scope for @code{alias this}
+before searching in upper scopes.
+@item in
+Implements @code{in} parameters to mean @code{scope const [ref]} and accepts
+rvalues.
+@item inclusiveincontracts
+Implements @code{in} contracts of overridden methods to be a superset of parent
+contract.
+@item intpromote
+Implements C-style integral promotion for unary @code{+}, @code{-} and @code{~}
+expressions.
+@item nosharedaccess
+Turns off and disallows all access to shared memory objects.
+@item rvaluerefparam
+Implements rvalue arguments to @code{ref} parameters.
+@item shortenedmethods
+Implements use of @code{=>} for methods and top-level functions in addition to
+lambdas.
+@end table
+
 @item -frelease
 @cindex @option{-frelease}
 @cindex @option{-fno-release}
@@ -291,6 +366,22 @@ gdc -fno-assert -fbounds-check=safe -fno-invariants \
     -fno-postconditions -fno-preconditions -fno-switch-errors
 @end example
 
+@item -frevert=
+@cindex @option{-frevert}
+Turns off a D language feature identified by @var{id}.  The following values
+are supported:
+
+@table @samp
+@item all
+Turns off all revertable D language features.
+@item dip25
+Reverts @uref{http://wiki.dlang.org/DIP25} (Sealed references).
+@item dtorfields
+Turns off generation for destructing fields of partially constructed objects.
+@item markdown
+Turns off Markdown replacements in Ddoc comments.
+@end table
+
 @item -fno-rtti
 @cindex @option{-frtti}
 @cindex @option{-fno-rtti}
@@ -524,6 +615,19 @@ Specify @var{file} as a @var{Ddoc} macro file to be read.  Multiple
 @option{-fdoc-inc} options can be used, and files are read and processed
 in the same order.
 
+@item -fdump-c++-spec=@var{file}
+For D source files, generate corresponding C++ declarations in @var{file}.
+
+@item -fdump-c++-spec-verbose
+In conjunction with @option{-fdump-c++-spec=} above, add comments for ignored
+declarations in the generated C++ header.
+
+@item -fsave-mixins=@var{file}
+@cindex @option{-fsave-mixins}
+Generates code expanded from D @code{mixin} statements and writes the
+processed sources to @var{file}.  This is useful to debug errors in compilation
+and provides source for debuggers to show when requested.
+
 @end table
 
 @node Warnings
@@ -633,19 +737,19 @@ Report additional information about D language changes identified by
 
 @table @samp
 @item all
-List information on all language changes.
+List information on all D language transitions.
 @item complex
 List all usages of complex or imaginary types.
-@item dip1000
-Implements @uref{http://wiki.dlang.org/DIP1000} (experimental).
-@item dip25
-Implements @uref{http://wiki.dlang.org/DIP25} (experimental).
 @item field
 List all non-mutable fields which occupy an object instance.
 @item nogc
 List all hidden GC allocations.
+@item templates
+List statistics on template instantiations.
 @item tls
 List all variables going into thread local storage.
+@item vmarkdown
+List instances of Markdown replacements in Ddoc.
 @end table
 
 @end table