Review of signature docs.

Doc/library/inspect.rst

@@ -397,25 +397,18 @@ Retrieving source code
 
 .. _inspect-signature-object:
 
-Introspecting callables with Signature Object
+Introspecting callables with the Signature object
----------------------------------------------
+-------------------------------------------------
-
-Signature object represents the call signature of a callable object and its
-return annotation.  To get a Signature object use the :func:`signature`
-function.
-
 
 .. versionadded:: 3.3
 
-.. seealso::
+The Signature object represents the call signature of a callable object and its
-
+return annotation.  To retrieve a Signature object, use the :func:`signature`
-   :pep:`362` - Function Signature Object.
+function.
-      The detailed specification, implementation details and examples.
-
 
 .. function:: signature(callable)
 
-   Returns a :class:`Signature` object for the given ``callable``::
+   Return a :class:`Signature` object for the given ``callable``::
 
       >>> from inspect import signature
       >>> def foo(a, *, b:int, **kwargs):
@@ -432,24 +425,24 @@ function.
       >>> sig.parameters['b'].annotation
       <class 'int'>
 
-   Accepts a wide range of python callables, from plain functions and classes
+   Accepts a wide range of python callables, from plain functions and classes to
-   to :func:`functools.partial` objects.
+   :func:`functools.partial` objects.
 
    .. note::
 
-      Some callables may not be introspectable in certain implementations
+      Some callables may not be introspectable in certain implementations of
-      of Python. For example, in CPython, built-in functions defined in C
+      Python.  For example, in CPython, built-in functions defined in C provide
-      provide no metadata about their arguments.
+      no metadata about their arguments.
 
 
 .. class:: Signature
 
-   A Signature object represents the call signature of a function and its
+   A Signature object represents the call signature of a function and its return
-   return annotation. For each parameter accepted by the function it
+   annotation.  For each parameter accepted by the function it stores a
-   stores a :class:`Parameter` object in its :attr:`parameters` collection.
+   :class:`Parameter` object in its :attr:`parameters` collection.
 
-   Signature objects are *immutable*. Use :meth:`Signature.replace` to make
+   Signature objects are *immutable*.  Use :meth:`Signature.replace` to make a
-   a modified copy.
+   modified copy.
 
    .. attribute:: Signature.empty
 
@@ -462,30 +455,29 @@ function.
 
    .. attribute:: Signature.return_annotation
 
-      The "return" annotation for the callable. If the callable has
+      The "return" annotation for the callable.  If the callable has no "return"
-      no "return" annotation, this attribute is set to
+      annotation, this attribute is set to :attr:`Signature.empty`.
-      :attr:`Signature.empty`.
 
    .. method:: Signature.bind(*args, **kwargs)
 
-      Creates a mapping from positional and keyword arguments to parameters.
+      Create a mapping from positional and keyword arguments to parameters.
-      Returns :class:`BoundArguments` if ``*args`` and ``**kwargs`` match
+      Returns :class:`BoundArguments` if ``*args`` and ``**kwargs`` match the
-      the signature, or raises a :exc:`TypeError`.
+      signature, or raises a :exc:`TypeError`.
 
    .. method:: Signature.bind_partial(*args, **kwargs)
 
-      Works the same way as :meth:`Signature.bind`, but allows the
+      Works the same way as :meth:`Signature.bind`, but allows the omission of
-      omission of some required arguments (mimics :func:`functools.partial`
+      some required arguments (mimics :func:`functools.partial` behavior.)
-      behavior.) Returns :class:`BoundArguments`, or raises a :exc:`TypeError`
+      Returns :class:`BoundArguments`, or raises a :exc:`TypeError` if the
-      if the passed arguments do not match the signature.
+      passed arguments do not match the signature.
 
    .. method:: Signature.replace([parameters], *, [return_annotation])
 
-      Creates a new Signature instance based on the instance replace was
+      Create a new Signature instance based on the instance replace was invoked
-      invoked on. It is possible to pass different ``parameters`` and/or
+      on.  It is possible to pass different ``parameters`` and/or
-      ``return_annotation`` to override the corresponding properties of
+      ``return_annotation`` to override the corresponding properties of the base
-      the base signature. To remove return_annotation from the copied
+      signature.  To remove return_annotation from the copied Signature, pass in
-      Signature, pass in :attr:`Signature.empty`.
+      :attr:`Signature.empty`.
 
       ::
 
@@ -497,38 +489,36 @@ function.
          "(a, b) -> 'new return anno'"
 
 
-
 .. class:: Parameter
 
-   Parameter objects are *immutable*. Instead of modifying a Parameter object,
+   Parameter objects are *immutable*.  Instead of modifying a Parameter object,
    you can use :meth:`Parameter.replace` to create a modified copy.
 
    .. attribute:: Parameter.empty
 
-      A special class-level marker to specify absence of default
+      A special class-level marker to specify absence of default values and
-      values and annotations.
+      annotations.
 
    .. attribute:: Parameter.name
 
-      The name of the parameter as a string. Must be a valid python identifier
+      The name of the parameter as a string.  Must be a valid python identifier
-      name (with the exception of ``POSITIONAL_ONLY`` parameters, which can
+      name (with the exception of ``POSITIONAL_ONLY`` parameters, which can have
-      have it set to ``None``.)
+      it set to ``None``).
 
    .. attribute:: Parameter.default
 
-      The default value for the parameter. If the parameter has no default
+      The default value for the parameter.  If the parameter has no default
       value, this attribute is set to :attr:`Parameter.empty`.
 
    .. attribute:: Parameter.annotation
 
-      The annotation for the parameter. If the parameter has no annotation,
+      The annotation for the parameter.  If the parameter has no annotation,
       this attribute is set to :attr:`Parameter.empty`.
 
    .. attribute:: Parameter.kind
 
-      Describes how argument values are bound to the parameter.
+      Describes how argument values are bound to the parameter.  Possible values
-      Possible values (accessible via :class:`Parameter`, like
+      (accessible via :class:`Parameter`, like ``Parameter.KEYWORD_ONLY``):
-      ``Parameter.KEYWORD_ONLY``):
 
       +------------------------+----------------------------------------------+
       |    Name                | Meaning                                      |
@@ -577,10 +567,10 @@ function.
 
    .. method:: Parameter.replace(*, [name], [kind], [default], [annotation])
 
-      Creates a new Parameter instance based on the instance replaced was
+      Create a new Parameter instance based on the instance replaced was invoked
-      invoked on. To override a :class:`Parameter` attribute, pass the
+      on.  To override a :class:`Parameter` attribute, pass the corresponding
-      corresponding argument. To remove a default value or/and an annotation
+      argument.  To remove a default value or/and an annotation from a
-      from a Parameter, pass :attr:`Parameter.empty`.
+      Parameter, pass :attr:`Parameter.empty`.
 
       ::
 
@@ -604,18 +594,18 @@ function.
    .. attribute:: BoundArguments.arguments
 
       An ordered, mutable mapping (:class:`collections.OrderedDict`) of
-      parameters' names to arguments' values. Contains only explicitly
+      parameters' names to arguments' values.  Contains only explicitly bound
-      bound arguments.  Changes in :attr:`arguments` will reflect in
+      arguments.  Changes in :attr:`arguments` will reflect in :attr:`args` and
-      :attr:`args` and :attr:`kwargs`.
+      :attr:`kwargs`.
 
-      Should be used in conjunction with :attr:`Signature.parameters` for
+      Should be used in conjunction with :attr:`Signature.parameters` for any
-      any arguments processing purposes.
+      argument processing purposes.
 
       .. note::
 
          Arguments for which :meth:`Signature.bind` or
          :meth:`Signature.bind_partial` relied on a default value are skipped.
-         However, if needed, it's easy to include them
+         However, if needed, it is easy to include them.
 
       ::
 
@@ -638,15 +628,16 @@ function.
 
    .. attribute:: BoundArguments.args
 
-      Tuple of positional arguments values. Dynamically computed
+      A tuple of positional arguments values.  Dynamically computed from the
-      from the :attr:`arguments` attribute.
+      :attr:`arguments` attribute.
 
    .. attribute:: BoundArguments.kwargs
 
-      Dict of keyword arguments values. Dynamically computed
+      A dict of keyword arguments values.  Dynamically computed from the
-      from the :attr:`arguments` attribute.
+      :attr:`arguments` attribute.
 
-   :attr:`args` and :attr:`kwargs` properties can be used to invoke functions::
+   The :attr:`args` and :attr:`kwargs` properties can be used to invoke
+   functions::
 
       def test(a, *, b):
          ...
@@ -656,6 +647,12 @@ function.
       test(*ba.args, **ba.kwargs)
 
 
+.. seealso::
+
+   :pep:`362` - Function Signature Object.
+      The detailed specification, implementation details and examples.
+
+
 .. _inspect-classes-functions:
 
 Classes and functions