Clarify per-argument type comments in PEP 484 (#126)

Author: ilevkivskyi

pep-0484.txt

@@ -1937,10 +1937,12 @@ Example::
 Sometimes you have a long list of parameters and specifying their
 types in a single ``# type:`` comment would be awkward.  To this end
 you may list the arguments one per line and add a ``# type:`` comment
-per line.  To specify the return type use the ellipsis syntax.  Not
-every argument needs to be given a type.  A line with a ``# type:``
-comment should contain exactly one argument.  The type comment for the
-last argument (if any) should precede the close parenthesis.  Example::
+per line after an argument's associated comma, if any.
+To specify the return type use the ellipsis syntax. Specifying the return
+type is not mandatory and not every argument needs to be given a type.
+A line with a ``# type:`` comment should contain exactly one argument.
+The type comment for the last argument (if any) should precede the close
+parenthesis. Example::
 
   def send_email(address,     # type: Union[str, List[str]]
                  sender,      # type: str
@@ -1959,14 +1961,17 @@ Notes:
   Python version being checked.  This is necessary in order to support
   code that straddles Python 2 and Python 3.
 
+- It is not allowed for an argument or return value to have both
+  a type annotation and a type comment.
+
 - When using the short form (e.g. ``# type: (str, int) -> None``)
   every argument must be accounted for, except the first argument of
   instance and class methods (those are usually omitted, but it's
   allowed to include them).
 
-- The return type is mandatory.  If in Python 3 you would omit some
-  argument or the return type, the Python 2 notation should use
-  ``Any``.
+- The return type is mandatory for the short form.  If in Python 3 you
+  would omit some argument or the return type, the Python 2 notation
+  should use ``Any``.
 
 - When using the short form, for ``*args`` and ``**kwds``, put 1 or 2
   stars in front of the corresponding type annotation.  (As with