Re: where should C++ options be documented?

[Martin Sebor <msebor at gmail dot com>]

On 04/03/2018 08:08 AM, Jason Merrill wrote:
> On Mon, Apr 2, 2018 at 9:33 PM, Martin Sebor <msebor@gmail.com> wrote:
> > Jason,
> >
> > The manual mentions some C++-only options in the language
> > independent section 3.8 Options to Request or Suppress
> > Warnings and others in 3.5 Options Controlling C++ Dialect.
> >
> > For example, -Wcatch-value, -Wconditionally-supported,
> > and -Wzero-as-null-pointer-constant are mentioned only
> > on the former page, while -Wabi-tag, -Wctor-dtor-privacy,
> > -Wliteral-suffix, and -Wclass-memaccess are mentioned only
> > on the latter.
> >
> > That makes C++ options harder to find than they should be.
> > It also makes it difficult to tell which C++ options are
> > included in -Wall or -Wextra.  I think we should converge
> > on the same approach for all C++ options that doesn't have
> > these problems.  What should it be?
> >
> > An approach that I think might work well is to continue
> > to mention even C++-only options in 3.8 but move their
> > descriptions to 3.5 (i.e., have the entry for each link
> > to the full description of the option on the C++ page).
>
> Sounds good.
>
> > Should I try to make this happen for GCC 8?
>
> Sure.

Attached is a prototype of what I have in mind.  It changes
just one option for illustration: -Wclass-memaccess.  Once
we're happy with the result I'll follow the same approach
for the rest of the C++ warning options.

To make it possible to jump directly to the detailed option
I had to add an explicit anchor.  That's an extra step that
would be nice to avoid.  The reference from -Wclass-memaccess
in 3.8 to the detailed option description in 3.5 renders like
this in HTML:

  See -Wclass-memaccess in Controlling C++ Dialect.

and like this in PDF:

  See [Wclass-memaccess], page 52 in Section 3.5 [Controlling C++ 
Dialect], page 42.

Martin

Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi	(revision 259040)
+++ gcc/doc/invoke.texi	(working copy)
@@ -270,7 +270,7 @@ Objective-C and Objective-C++ Dialects}.
 -Wc++-compat  -Wc++11-compat  -Wc++14-compat  @gol
 -Wcast-align  -Wcast-align=strict  -Wcast-function-type  -Wcast-qual  @gol
 -Wchar-subscripts  -Wchkp  -Wcatch-value  -Wcatch-value=@var{n} @gol
--Wclobbered  -Wcomment  -Wconditionally-supported @gol
+-Wclass-memaccess -Wclobbered  -Wcomment  -Wconditionally-supported @gol
 -Wconversion  -Wcoverage-mismatch  -Wno-cpp  -Wdangling-else  -Wdate-time @gol
 -Wdelete-incomplete @gol
 -Wno-deprecated  -Wno-deprecated-declarations  -Wno-designated-init @gol
@@ -3006,8 +3006,10 @@ void h() @{ f(g); @}
 In C++14, @code{f} calls calls @code{f<void(*)()>}, but in
 C++17 it calls @code{f<void(*)()noexcept>}.
 
-@item -Wclass-memaccess @r{(C++ and Objective-C++ only)}
+@anchor{Wclass-memaccess}
+@item -Wno-class-memaccess @r{(C++ and Objective-C++ only)}
 @opindex Wclass-memaccess
+@opindex Wno-class-memaccess
 Warn when the destination of a call to a raw memory function such as
 @code{memset} or @code{memcpy} is an object of class type, and when writing
 into such an object might bypass the class non-trivial or deleted constructor
@@ -3914,6 +3916,7 @@ Options} and @ref{Objective-C and Objective-C++ Di
 -Wc++11-compat  -Wc++14-compat  @gol
 -Wcatch-value @r{(C++ and Objective-C++ only)}  @gol
 -Wchar-subscripts  @gol
+-Wclass-memaccess @r{(C++ and Objective-C++ only)}  @gol
 -Wcomment  @gol
 -Wduplicate-decl-specifier @r{(C and Objective-C only)} @gol
 -Wenum-compare @r{(in C/ObjC; this is on by default in C++)} @gol
@@ -4029,6 +4032,11 @@ of error, as programmers often forget that this ty
 machines.
 This warning is enabled by @option{-Wall}.
 
+@item -Wno-class-memaccess @r{(C++ and Objective-C++ only)}
+@opindex Wclass-memaccess
+@opindex Wno-class-memaccess
+See @ref{Wclass-memaccess,@option{-Wclass-memaccess}} in @ref{C++ Dialect Options,,Controlling C++ Dialect}.
+
 @item -Wchkp
 @opindex Wchkp
 Warn about an invalid memory access that is found by Pointer Bounds Checker