Apply suggestions from code review

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
python · hugovk · Apr 24, 2023 · Apr 5, 2023 · Apr 7, 2023 · Apr 7, 2023
commit c2c299786d9938cfbaa2876cfb1c31483346f235
@@ -258,7 +258,7 @@ Here is what is happening:
 
 * To show that the option is actually optional, there is no error when running
   the program without it. Note that by default, if an optional argument isn't
-  used, the relevant variable, in this case :attr:`!args.verbosity`, is
+  used, the relevant variable, in this case ``args.verbosity``, is
   given ``None`` as a value, which is the reason it fails the truth
   test of the :keyword:`if` statement.
 
@@ -301,7 +301,7 @@ Here is what is happening:
   We even changed the name of the option to match that idea.
   Note that we now specify a new keyword, ``action``, and give it the value
   ``"store_true"``. This means that, if the option is specified,
-  assign the value ``True`` to :data:`!args.verbose`.
+  assign the value ``True`` to ``args.verbose``.
   Not specifying it implies ``False``.
 
 * It complains when you specify a value, in true spirit of what flags

@@ -585,7 +585,7 @@ arguments will never be treated as file references.
 
 .. versionchanged:: 3.12
    :class:`ArgumentParser` changed encoding and errors to read arguments files
-   from default (e.g. :func:`locale.getpreferredencoding(False) <locale.getpreferredencoding()>` and
+   from default (e.g. :func:`locale.getpreferredencoding(False) <locale.getpreferredencoding>` and
    ``"strict"``) to :term:`filesystem encoding and error handler`.
    Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows.
 
@@ -2308,4 +2308,4 @@ Exceptions
 
 .. exception:: ArgumentTypeError
 
-   An error from trying to convert a command line string to a type.
+   Raised when something goes wrong converting a command line string to a type.
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
@@ -952,11 +952,18 @@ The canonical way to create an :class:`Option` instance is with the
    you may also supply :attr:`~Option.type` and :attr:`~Option.dest` option
    attributes; see :ref:`optparse-standard-option-actions`.)
 
-.. class:: Values
-
 As you can see, most actions involve storing or updating a value somewhere.
 :mod:`optparse` always creates a special object for this, conventionally called
-``options`` (it happens to be an instance of :class:`optparse.Values`).  Option
+``options``, which is an instance of :class:`optparse.Values`.
+
+.. class:: Values
+
+   An object holding parsed argument names and values as attributes.
+   Normally created by calling when calling :meth:`OptionParser.parse_args`,
+   and can be overridden by a custom subclass passed to the *values* argument of 
+   :meth:`OptionParser.parse_args` (as described in :ref:`optparse-parsing-arguments`).
+
+Option
 arguments (and various other values) are stored as attributes of this object,
 according to the :attr:`~Option.dest` (destination) option attribute.
 
@@ -995,6 +1002,12 @@ Option attributes
 
 .. class:: Option
 
+   A single command line argument,
+   with various attributes passed by keyword to the constructor.
+   Normally created with :meth:`OptionParser.add_option` rather than directly,
+   and can be overridden by a custom class via the *option_class* argument
+   to :class:`OptionParser`.
+
 The following option attributes may be passed as keyword arguments to
 :meth:`OptionParser.add_option`.  If you pass an option attribute that is not
 relevant to a particular option, or fail to pass a required option attribute,
@@ -2058,8 +2071,8 @@ Exceptions
 
 .. exception:: BadOptionError
 
-    Raised if an invalid option is seen on the command line.
+   Raised if an invalid option is passed on the command line.
 
 .. exception:: AmbiguousOptionError
 
-    Raised if an ambiguous option is seen on the command line.
+   Raised if an ambiguous option is passed on the command line.