Add some clarifications to the PEP and implementation link (GH-907)

pep-0570.rst

@@ -37,15 +37,32 @@ of it. But, this is not always desired nor even available as
 even in current versions of Python, many CPython
 "builtin" functions still only accept positional-only arguments.
 
+Users might want to restrict their API to not allow for parameters
+to be referenced via keyword, as that exposes the name of the
+parameter as part of the API. If a user of said API starts using the
+argument by keyword when calling it and then the name of the parameter
+is changed, it will be a breaking change. By using positional-only
+parameters the developer can later change the name of an argument or
+transform them to ``*args`` without breaking the API.
+
 Even if positional arguments only in a function can be achieved
 via using ``*args`` parameters and extracting them one by one,
 the solution is far from ideal and not as expressive as the one
 proposed in this PEP, which targets to provide syntax to specify
-accepting a specific number of positional-only parameters.
+accepting a specific number of positional-only parameters. Also,
+it makes the signature of the function ambiguous as users won't
+know how many parameters the function takes by looking at help()
+or auto-generated documentation.
+
 Additionally, this will bridge the gap we currently find between
 builtin functions that today allows to specify positional-only
 parameters and pure Python implementations that lack the
-syntax for it.
+syntax for it. The '/' syntax is already exposed in the
+documentation for some builtins and interfaces generated by
+the argument clinic. Making positional only arguments a possibility
+in Python will bring consistency and will remove confusion from
+users that are not familiarized with the fact that positional only
+arguments are allowed in builtins and argument clinic C interfaces.
 
 -----------------------------------------------------
 Positional-Only Parameter Semantics In Current Python
@@ -87,7 +104,8 @@ Obviously one can simulate any of these in pure Python code
 by accepting ``(*args, **kwargs)`` and parsing the arguments
 by hand.  But this results in a disconnect between the
 Python function signature and what it actually accepts,
-not to mention the work of implementing said argument parsing.
+not to mention the work of implementing said argument parsing
+and the lack of clarity that generates in the signature.
 
 ==========
 Motivation
@@ -170,38 +188,29 @@ Full grammar specification
 A draft of the proposed grammar specification is::
 
     new_typedargslist:
-      tfpdef (',' tfpdef)* ',' '/' [',' [typedargslist]] | typedargslist
+      tfpdef ['=' test] (',' tfpdef ['=' test])* ',' '/' [',' [typedargslist]] | typedargslist
 
     new_varargslist:
-      vfpdef (',' vfpdef)* ',' '/' [',' [varargslist]] | varargslist
+      vfpdef ['=' test] (',' vfpdef ['=' test])* ',' '/' [',' [varargslist]] | varargslist
 
-It will be added to the actual typedargslist and varargslist
+It will be added to the actual typedargslist and varargslist but for easier discussion is
-but for easier discussion is presented as new_typedargslist and new_varargslist
+presented as new_typedargslist and new_varargslist. Also, notice that using a construction
+using two new rules (new_varargslist and new_varargslist) is not possible with the current
+parser as the rule is not LL(1). This is the reason the rule needs to be include in the
+existing typedargslist and varargslist (in the same way keyword-only arguments were introduced).
 
 
-===================
+==============
-Implementation Plan
+Implementation
-===================
+==============
 
-The implementation will involve a full change of the Grammar. This will
+An initial implementation that passes the CPython test suite is available
-involve following the steps outlined in PEP 306 [#PEP306]_. In addition, other
+for evaluation [#posonly-impl]_.
-steps are needed including:
-
-* Modifying the code object and the function object to be aware of positional
-  only arguments.
-
-* Modifiying ``ceval.c`` (``PyEval_EvalCodeEx``, ``PyEval_EvalFrameEx``...)
-  to correctly handle positional-only arguments.
-
-* Modifying ``marshal.c`` to account for the modifications of the code object.
-
-
-This does not intend to be a guide or a comprehensive recipe on how to implement
-this but a rough outline of the changes this will make to the codebase.
 
 The advantages of this implementation involve speed, consistency with the
-implementation of keyword-only parameters as in PEP 3102 and a simpler implementation
+implementation of keyword-only parameters as in PEP 3102 and a simpler
-of all the tools and modules that will be impacted by this change.
+implementation of all the tools and modules that will be impacted by
+this change.
 
 ==============
 Rejected Ideas
@@ -315,6 +324,9 @@ Braulio Valdivieso.
 .. [#python-ideas-decorator-based]
    https://mail.python.org/pipermail/python-ideas/2017-February/044888.html
 
+.. [#posonly-impl]
+   https://github.com/pablogsal/cpython_positional_only
+
 =========
 Copyright
 =========