PEP 677: Minor wording and formatting fixes. (#2225)

We're getting ready for a final request for comments to python-dev,
so I did one more pass through the PEP to catch remaining readability
issues (I was especially looking for things easier to see on the actual
PEP page with formatting than the rst doc):
- found an incorrectly formatted hyperlink
- changed some sentences with ambiguous pronouns
- broke up a couple of sentences that seemed too long
- tweaked a few places where the wording was okay but nonstandard

Author: stroxler

pep-0677.rst

@@ -18,7 +18,7 @@ This PEP introduces a concise and friendly syntax for callable types,
 supporting the same functionality as ``typing.Callable`` but with an
 arrow syntax inspired by the syntax for typed function
 signatures. This allows types like ``Callable[[int, str], bool]`` to
-be written ``(int, str) -> bool``.
+be written as ``(int, str) -> bool``.
 
 The proposed syntax supports all the functionality provided by
 ``typing.Callable`` and ``typing.Concatenate``, and is intended to
@@ -78,7 +78,7 @@ There are a few usability challenges with ``Callable`` we can see here:
 - The bracket structure is not visually similar to how function signatures
   are written.
 - It requires an explicit import, unlike many of the other most common
-  types like ``list``.
+  types like ``list`` and ``dict``.
 
 Possibly as a result, `programmers often fail to write complete
 Callable types
@@ -102,8 +102,8 @@ the benefits of static typing. For example, they might write this::
     flat_map(add, [1, 2, 3])  # oops, no type check error!
 
 There's some partial type information here - we at least know that ``func``
-needs to be callable. But we've dropped too much type information to catch
-the mistake.
+needs to be callable. But we've dropped too much type information for
+type checkers to find the bug.
 
 With our proposal, the example looks like this::
 
@@ -142,7 +142,7 @@ types, is more complicated to read and write, and still requires an
 import and bracket-based syntax.
 
 In this proposal, we chose to support all the existing semantics of
-``typing.Callable``, without adding support for new features. We took
+``typing.Callable``, without adding support for new features. We made
 this decision after examining how frequently each feature might be
 used in existing typed and untyped open-source code. We determined
 that the vast majority of use cases are covered.
@@ -296,8 +296,8 @@ It also optionally allows adding names to the arguments, for example::
 
     (x: Int, y: String) -> Bool
 
-As in TypeScript, the argument names if provided are just there for documentation
-and are not part of the type itself.
+As in TypeScript, the argument names (if provided) are just there for
+documentation and are not part of the type itself.
 
 Scala
 ~~~~~
@@ -315,11 +315,11 @@ Function types can optionally include names, for example::
 
 Unlike in TypeScript and Kotlin, these names are part of the type if
 provided - any function implementing the type must use the same names.
-This is similar to the extended syntax proposal we described in our
+This is similar to the extended syntax proposal we describe in our
 `Rejected Alternatives`_ section.
 
-Function Definition vs Callable Type Annotations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Function Definitions vs Callable Type Annotations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In all of the languages listed above, type annotations for function
 definitions use a ``:`` rather than a ``->``. For example, in TypeScript
@@ -542,7 +542,7 @@ Trailing Commas
 ~~~~~~~~~~~~~~~
 
 - Following the precedent of function signatures, putting a comma in
-  an empty arguments list is illegal, ``(,) -> bool`` is a syntax
+  an empty arguments list is illegal: ``(,) -> bool`` is a syntax
   error.
 - Again following precedent, trailing commas are otherwise always
   permitted::
@@ -710,7 +710,7 @@ We decided against proposing it for the following reasons:
   demonstrate that fewer than 3% of use cases would benefit from any
   of the added features.
 - The group that debated these proposals was split down the middle
-  about whether these changes are even desirable:
+  about whether these changes are desirable:
 
   - On the one hand, they make callable types more expressive. On the
     other hand, they could easily confuse users who have not read the
@@ -723,8 +723,8 @@ We decided against proposing it for the following reasons:
 - We intend to implement the current proposal in a way that is
   forward-compatible with the more complicated extended syntax. If the
   community decides after more experience and discussion that we want
-  the additional features, they should be straightforward to propose
-  in the future.
+  the additional features, it should be straightforward to propose
+  them in the future.
 - Even a full extended syntax cannot replace the use of callback
   protocols for overloads. For example, no closed form of callable type
   could express a function that maps bools to bools and ints to floats,
@@ -752,7 +752,8 @@ We decided against proposing it for the following reasons:
 We confirmed that the current proposal is forward-compatible with
 extended syntax by
 `implementing <https://github.com/stroxler/cpython/tree/callable-type-syntax--extended>`_
-a quick-and-dirty grammar and AST on top of this grammar and AST for.
+a grammar and AST for this extended syntax on top of our reference
+implementation of this PEP's grammar.
 
 
 Syntax Closer to Function Signatures
@@ -778,11 +779,10 @@ The benefits of this proposal would have included:
 
 Key downsides that led us to reject the idea include the following:
 
-- A large majority of use cases only use positional-only arguments,
-  and this syntax would be more verbose for that use case, both
-  because of requiring argument names and an explicit ``/``, for
-  example ``(int, /) -> bool`` where our proposal allows ``(int) ->
-  bool``
+- A large majority of use cases only use positional-only arguments.  This
+  syntax would be more verbose for that use case, both because of requiring
+  argument names and an explicit ``/``, for example ``(int, /) -> bool`` where
+  our proposal allows ``(int) -> bool``
 - The requirement for explicit ``/`` for positional-only arguments has
   a high risk of causing frequent bugs - which often would not be
   detected by unit tests - where library authors would accidentally
@@ -982,8 +982,7 @@ This actually is a significant readability improvement for
 multi-argument functions, but the problem is that it makes callables
 with one arguments, which are the most common arity, hard to
 write: because ``(x)`` evaluates to ``x``, they would have to be
-written like ``callable[(int,), bool]``. This is awkward enough that
-we dislike this idea.
+written like ``callable[(int,), bool]``. We find this awkward.
 
 Moreover, none of these ideas help as much with reducing verbosity
 as the current proposal, nor do they introduce as strong a visual cue
@@ -1078,8 +1077,8 @@ types. However, we have since begun to do so, e.g. with PEP 604.
 at the PyCon Typing Summit 2021.
 
 **Steven** `brought up this proposal on typing-sig
-<https://mail.python.org/archives/list/[email protected]/thread/3JNXLYH5VFPBNIVKT6FFBVVFCZO4GFR2>`. We
-had several meetings to discuss alternatives, and `this presentation
+<https://mail.python.org/archives/list/[email protected]/thread/3JNXLYH5VFPBNIVKT6FFBVVFCZO4GFR2>`_.
+We had several meetings to discuss alternatives, and `this presentation
 <https://www.dropbox.com/s/sshgtr4p30cs0vc/Python%20Callable%20Syntax%20Proposals.pdf?dl=0>`_
 led us to the current proposal.