This is the mail archive of the gcc@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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".




Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]