This is super helpful!
>From the recent discussion in the a68 front-end patch series, perhaps
the following is worth documenting as a guideline?
* When adding an option that is specific to a front end, please do not
include the name of the language or front end in the option name
unless the option is intended for debugging or other internal
purposes. It is safe to assume the user is aware of the compiler she
is using.
> After working through PR122243, it seems appropriate to write down
> some guidelines for adding/maintaining options and options
> documentation so that we can at least point to procedures to keep
> things from getting out of sync again.
>
> gcc/ChangeLog
> * doc/options.texi (Options): Point to the "user experience"
> documentation.
> * doc/ux.texi (Guidelines for Options): Add some.
> ---
> gcc/doc/options.texi | 2 ++
> gcc/doc/ux.texi | 80 +++++++++++++++++++++++++++++++++++++++++++-
> 2 files changed, 81 insertions(+), 1 deletion(-)
>
> diff --git a/gcc/doc/options.texi b/gcc/doc/options.texi
> index 2201423f4f3..2a1d7e32fbd 100644
> --- a/gcc/doc/options.texi
> +++ b/gcc/doc/options.texi
> @@ -10,6 +10,8 @@
> Most GCC command-line options are described by special option
> definition files, the names of which conventionally end in
> @code{.opt}. This chapter describes the format of these files.
> +For information about managing GCC options and the user experience,
> +@ref{Guidelines for Options}.
>
> @menu
> * Option file format:: The general layout of the files
> diff --git a/gcc/doc/ux.texi b/gcc/doc/ux.texi
> index 3251e115746..ddc857e8fd4 100644
> --- a/gcc/doc/ux.texi
> +++ b/gcc/doc/ux.texi
> @@ -748,4 +748,82 @@ generated patches.
> @cindex options, guidelines for
> @cindex guidelines for options
>
> -@c TODO
> +@xref{Options}, for information about how GCC command-line options are
> +defined in @code{.opt} files.
> +
> +Please follow existing conventions for option naming. Target-specific
> +options should begin with @samp{-m}, general code generation and
> +optimization options with @samp{-f}, options controlling diagnostic
> +messages with @samp{-W}, and options controlling debug output with
> +@samp{-g}. In each of these four categories there is a corresponding
> +negative form for each option beginning with @samp{-mno-},
> +@samp{-fno-}, @samp{-Wno-}, or @samp{-gno-} (respectively), which
> +allow users to override a positive form of the option earlier on the
> +command line.
> +
> +For options that take an argument, the negative form often does not
> +make sense; in this case, specify the @samp{RejectNegative} attribute
> +on the definition in the @code{.opt} file. If you want to add an
> +option that @emph{only} has a negative form (perhaps to disable a
> +positive-form multiple-choice option that takes an argument), list it
> +in the @code{.opt} file in its @samp{no-} form and also add
> +@samp{RejectNegative}.
> +
> +When you add a new option that is intended to be visible to users,
> +you should add documentation for it in the same commit. C language
> +family and language-independent options are documented in the main GCC
> +manual (in @file{invoke.texi} or files included by it), while
> +options specific to the front ends for other languages, like Fortran,
> +are documented in the corresponding manual.
> +
> +For options documented in the GCC manual, the required documentation is:
> +
> +@itemize @bullet{}
> +@item Add the option to the appropriate table in the Option Summary section
> +(@pxref{Option Summary,,Option Summary,gcc,Using the GNU Compiler
> Collection}).
> +Only add one of the positive or negative forms here.
> +Use two spaces to separate options listed on the same line.
> +@item Add detailed documentation to the corresponding subsection. It is
> +only necessary to document one of the positive or negative forms, but
> sometimes
> +it's appropriate to list both.
> +@item Add index entries for @emph{both} the positive and negative forms just
> +before the detailed documentation.
> +@end itemize
> +
> +If an option is not intended to be user visible (for example, it's used only
> +to support testing, back-end debugging, or to experiment with new features
> +that are not ready or stable enough for general use), you should explicitly
> +specify the @samp{Undocumented} property in the @code{.opt} file definition
> +so it is clear to other maintainers that the lack of documentation is
> +deliberate.
> +
> +Parameters (@samp{--param=}) are special options that allow control
> +over constants affecting GCC's internal behavior. Since these are also
> +not intended to be user-visible, they need not be documented or explicitly
> +marked as @samp{Undocumented}.
> +
> +Sometimes options become obsolete. There are several choices of what to do
> +here.
> +@itemize @bullet{}
> +@item You can remove the entry entirely from the @code{.opt} file. This
> +typically causes a generic error if GCC is invoked with that option.
> +@item You can add the @samp{WarnRemoved} attribute to the option definition.
> +This results in a more specific error message.
> +@item You can add the @samp{Warn} attribute to the option definition. For
> +example, you can use this if you want to warn that an option is deprecated,
> +rather than remove it completely.
> +@item You can add the @samp{Ignore} attribute to the option definition to
> +silently ignore it and do nothing if it is passed. This has the advantage
> +that it won't break old makefiles, but is only appropriate if the default
> +behavior without the option is consistent with the previous behavior with
> +the option and doesn't conflict with user expectations.
> +@end itemize
> +
> +In all of these cases, you should remove the user documentation for an option
> +at the same time you remove, disable, or deprecate it.
> +
> +If you add, remove, or modify options documentation, you must also run
> +@samp{make regenerate-opt-urls} in the @file{gcc} directory of your
> +build tree, and check in the resulting changes. This updates the
> +database used to insert links to the online documentation for options
> +that are mentioned in diagnostic messages.
