This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: Documentation style for options with optional levels
On 10/04/19 08:42 -0400, Nathan Sidwell wrote:
On 4/10/19 7:13 AM, Jonathan Wakely wrote:
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?
yes?
Thought so. "Somebody" should do something about this ;-)
All the examples you give leave something to be desired.
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}
The @item is the clearest to read, and also the most accurate as it
shows you can provide it without a level. But from that snippet
there's no indication what not giving a level gets you. There needs
to be some words somewhere to say what it maps to.
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).
.. for example that, I can't tell if I can say just -Wshift-overflow
and get level 1, or if I'll get level 1 whatever unless I say
-Wno-shift-overflow
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.
In context with the other levels, I see that is trying to tell you
that 1 is the default, but it's unclear. My first reading was that 1
gets you a warning level, (with the implication that 2 got you an
error level or something?)
Right. Too often you have to try and infer what it's saying, and when
every case is presented differently you can't even apply the same
inferences to different options!
If we decide on a way to document these cases that is clear and
unambiguous, I'll volunteer to go through the existing docs and usee
that style.