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