This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Documentation style for options with optional levels
- From: Jonathan Wakely <jwakely at redhat dot com>
- To: gcc at gcc dot gnu dot org
- Date: Wed, 10 Apr 2019 12:13:26 +0100
- Subject: Documentation style for options with optional levels
For options that can be used as -foo or -foo=level we have a variety
of different styels for documenting what the default level is. See
below for several examples. I find this a bit confusing when try to
see what it means to use the option without a level.
Do we want to pick a style and try to be consistent?
For -Wformat-overflow we show the option with and without the level:
@item -Wformat-overflow
@itemx -Wformat-overflow=1
@opindex Wformat-overflow
@opindex Wno-format-overflow
Level @var{1} of @option{-Wformat-overflow} enabled by @option{-Wformat}
For -Wshift-overflow we use prose to say what omitting the level
means:
@item -Wshift-overflow=1
This is the warning level of @option{-Wshift-overflow} and is enabled
by default in C99 and C++11 modes (and newer).
Similarly for -Wunused-const-variable:
@item -Wunused-const-variable=1
This is the warning level that is enabled by @option{-Wunused-variable} for
C.
For -Wstrict-aliasing we add it to the sub-heading for the description
of the corresponding level:
Level 3 (default for @option{-Wstrict-aliasing}):
For -Wstrict-overflow we add a sentence to the end of the paragraph
about the corresponding level:
@item -Wstrict-overflow=2
Also warn about other cases where a comparison is simplified to a
constant. For example: @code{abs (x) >= 0}. This can only be
simplified when signed integer overflow is undefined, because
@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
zero. @option{-Wstrict-overflow} (with no level) is the same as
@option{-Wstrict-overflow=2}.
For -Warray-bounds we list both options separately, and then also list
the forms with levels and say what no level means:
@item -Warray-bounds
@itemx -Warray-bounds=@var{n}
@opindex Wno-array-bounds
@opindex Warray-bounds
This option is only active when @option{-ftree-vrp} is active
(default for @option{-O2} and above). It warns about subscripts to arrays
that are always out of bounds. This warning is enabled by @option{-Wall}.
@table @gcctabopt
@item -Warray-bounds=1
This is the warning level of @option{-Warray-bounds} and is enabled
by @option{-Wall}; higher levels are not, and must be explicitly requested.
For -Wattribute-alias and -Wplacement-new we do the same as -Warray-bounds.
For -Wnormalized we use prose:
There are four levels of warning supported by GCC@. The default is
@option{-Wnormalized=nfc}, which warns about any identifier that is
For -g we say:
@item -g@var{level}
@itemx -ggdb@var{level}
@itemx -gstabs@var{level}
@itemx -gxcoff@var{level}
@itemx -gvms@var{level}
Request debugging information and also use @var{level} to specify how
much information. The default level is 2.
For -flive-patching we add a paragraph at the end:
When @option{-flive-patching} is specified without any value, the default value
is "inline-clone".