Documentation style for options with optional levels

Documentation style for options with optional levels

[Jonathan Wakely]

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

Re: Documentation style for options with optional levels

[Nathan Sidwell]

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?

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?)

nathan


-- 
Nathan Sidwell

Re: Documentation style for options with optional levels

[Jonathan Wakely]

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.

Re: Documentation style for options with optional levels

[Sandra Loosemore]

On 4/10/19 5: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?

I think part of the problem here is that it collides with the existing 
convention that we document the -foo form for options that default to 
off and the -no-foo form for options that default to on, and we probably 
have instances of both flavors that were originally binary options but 
now take an optional level.  Plus people tack on to the documentation 
incrementally for new options and don't always check for or copy the 
style of documentation for similar option syntax elsewhere.

I suspect anything we do will eventually get bit-rotten anyway, but if 
you want a convention, I'd propose that we always document -foo=level as 
the primary form and explicitly list whichever of -foo and/or -no-foo 
are also supported (regardless of the default), with information in the 
text about what level they correspond to, what the default is, etc. 
E.g. roughly following this organization:

@item -foo=@var{level}
@itemx -foo
@itemx -no-foo
@opindex foo

This option controls....
The @var{level} may be one of....

@option{-foo} without a @var{level} is equivalent to....
@option{-fno-foo} is equivalent to....

The default is....  [and/or information about what setting is implied by 
other options].

-Sandra

Re: Documentation style for options with optional levels

[Martin Sebor]

On 4/10/19 9:46 AM, Sandra Loosemore wrote:
> On 4/10/19 5: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?
> 
> I think part of the problem here is that it collides with the existing 
> convention that we document the -foo form for options that default to 
> off and the -no-foo form for options that default to on, and we probably 
> have instances of both flavors that were originally binary options but 
> now take an optional level.  Plus people tack on to the documentation 
> incrementally for new options and don't always check for or copy the 
> style of documentation for similar option syntax elsewhere.
> 
> I suspect anything we do will eventually get bit-rotten anyway, but if 
> you want a convention, I'd propose that we always document -foo=level as 
> the primary form and explicitly list whichever of -foo and/or -no-foo 
> are also supported (regardless of the default), with information in the 
> text about what level they correspond to, what the default is, etc. E.g. 
> roughly following this organization:
> 
> @item -foo=@var{level}
> @itemx -foo
> @itemx -no-foo
> @opindex foo
> 
> This option controls....
> The @var{level} may be one of....
> 
> @option{-foo} without a @var{level} is equivalent to....
> @option{-fno-foo} is equivalent to....
> 
> The default is....  [and/or information about what setting is implied by 
> other options].

I find the -ffoo vs -fno-foo convention very confusing, not only
because I never know if the manual is correct.

Rather than trusting ourselves to get it right, could these details
be generated instead?  It seems the option processing AWK scripts
should be able to extract this from the .opt files fill it in
the right places in the .texi files, shouldn't they?  All they
would need is some markup to know what to replace.

Martin