The latest round of changes from Yury Selivanov on PEP 362.

pep-0362.txt

@@ -72,18 +72,25 @@ Signature objects are immutable.  Use ``Signature.replace()`` to
 make a modified copy:
 ::
 
+    >>> def foo() -> None:
+    ...     pass
     >>> sig = signature(foo)
+
     >>> new_sig = sig.replace(return_annotation="new return annotation")
     >>> new_sig is not sig
     True
-    >>> new_sig.return_annotation == sig.return_annotation
+    >>> new_sig.return_annotation != sig.return_annotation
     True
     >>> new_sig.parameters == sig.parameters
     True
 
+    >>> new_sig = new_sig.replace(return_annotation=new_sig.empty)
+    >>> hasattr(new_sig, "return_annotation")
+    False
+
 There are two ways to instantiate a Signature class:
 
-* Signature(parameters, *, return_annotation)
+* Signature(parameters, \*, return_annotation)
     Default Signature constructor.  Accepts an optional sequence
     of ``Parameter`` objects, and an optional ``return_annotation``.
     Parameters sequence is validated to check that there are no
@@ -166,6 +173,9 @@ A Parameter object has the following public attributes and methods:
          that aren't bound to any other parameter. This corresponds
          to a "\*\*kwds" parameter in a Python function definition.
 
+    Always use ``Parameter.*`` constants for setting and checking
+    value of the ``kind`` attribute.
+
 * replace(\*, name, kind, default, annotation) -> Parameter
     Creates a new Parameter instance based on the instance
     ``replaced`` was invoked on.  To override a Parameter
@@ -173,6 +183,12 @@ A Parameter object has the following public attributes and methods:
     an attribute from a ``Parameter``, pass ``Parameter.empty``.
 
 
+Parameter constructor:
+
+* Parameter(name, kind, \*, annotation, default)
+   Instantiates a Parameter object. ``name`` and ``kind`` are required,
+   while ``annotation`` and ``default`` are optional.
+
 Two parameters are equal when they have equal names, kinds, defaults,
 and annotations.
 
@@ -283,9 +299,8 @@ The function implements the following algorithm:
     - Return ``signature(object.__call__)``
 
 Note that the ``Signature`` object is created in a lazy manner, and
-is not automatically cached.  If, however, the Signature object was
-explicitly cached by the user, ``signature()`` returns a new shallow copy
-of it on each invocation.
+is not automatically cached.  However, the user can manually cache a
+Signature by storing it in the ``__signature__`` attribute.
 
 An implementation for Python 3.3 can be found at [#impl]_.
 The python issue tracking the patch is [#issue]_.
@@ -323,9 +338,9 @@ Signature and Parameter equivalence
 -----------------------------------
 
 We assume that parameter names have semantic significance--two
-signatures are equal only when their corresponding parameters have
-the exact same names.  Users who want looser equivalence tests, perhaps
-ignoring names of VAR_KEYWORD or VAR_POSITIONAL parameters, will
+signatures are equal only when their corresponding parameters are equal
+and have the exact same names.  Users who want looser equivalence tests,
+perhaps ignoring names of VAR_KEYWORD or VAR_POSITIONAL parameters, will
 need to implement those themselves.