PEP 727: Rewordings and clarifications (#3315)

pep-0727.rst

@@ -2,14 +2,14 @@ PEP: 727
 Title: Documentation Metadata in Typing
 Author: Sebastián Ramírez <tiangolo@gmail.com>
 Sponsor: Jelle Zijlstra <jelle.zijlstra@gmail.com>
-Discussions-To:
+Discussions-To: https://discuss.python.org/t/pep-727-documentation-metadata-in-typing/32566
 Status: Draft
 Type: Standards Track
 Topic: Typing
 Content-Type: text/x-rst
 Created: 28-Aug-2023
 Python-Version: 3.13
-Post-History:
+Post-History: `30-Aug-2023 <https://discuss.python.org/t/pep-727-documentation-metadata-in-typing/32566>`__
 
 
 Abstract
@@ -45,11 +45,17 @@ the actual parameter. This means it's easy to refactor a function, remove a para
 and forget to remove its docs. The same happens when adding a new parameter: it's easy
 to forget to add the docstring for it.
 
-Editors can't check or ensure the consistency of the parameters and their docs.
+And because of this same duplication of information (the parameter name) editors and
+other tools would need to have complex custom logic to check or ensure the
+consistency of the parameters in the signature and in their docstring, or they
+would simply not be able to support that.
 
-It's not possible to programatically test these docstrings, for example to ensure
-documentation consistency for the parameters across several similar functions, at
-least not without implementing a custom syntax parser.
+Additionally, it would be difficult to robustly parse varying existing docstring
+conventions to programatically get the documentation for each individual parameter
+or variable at runtime. This would be useful, for example,
+for testing the contents of each parameter's documentation, to ensure consistency
+across several similar functions, or to extract and expose that same parameter
+documentation in some other way (e.g. an API, a CLI, etc).
 
 Some of these previous formats tried to account for the lack of type annotations
 in older Python versions by including typing information in the docstrings,