Apply suggestions from code review

Co-authored-by: Hugo van Kemenade <[email protected]>

peps/pep-9999.rst

@@ -58,17 +58,17 @@ time updating it for use cases that it was not originally designed for.
 
 However, there was also a sense at the Language Summit that we are
 trying to discuss solutions without a clear common understanding
-of the problems that we are trying to solve. It was decided that
+of the problems that we are trying to solve. We decided that
 we need to agree on the current problems with the C API, before
 we are able to evaluate any of the proposed solutions. We
 therefore created the
-[`capi-workgroup <https://github.com/capi-workgroup/problems/issues/>`__]
+`capi-workgroup <https://github.com/capi-workgroup/problems/issues/>`__
 repository on GitHub in order to collect everyone's ideas on that
 question.
 
 Over 60 different issues were created on that repository, each
-describing a problem with the C API. They were categorized and
-a number of recurring themes were identified. The sections below
+describing a problem with the C API. We categorized them and
+identified a number of recurring themes. The sections below
 mostly correspond to these themes, and each contains a combined
 description of the issues raised in that category, along with
 links to the individual issues. In addition, we included a section
@@ -82,7 +82,7 @@ C API Stakeholders
 As mentioned in the introduction, the C API was originally
 created as the internal interface between CPython's
 interpreter and the Python layer. It was later exposed as
-a way for third party developers to extend and embed Python
+a way for third-party developers to extend and embed Python
 programs. Over the years, new types of stakeholders emerged,
 with different requirements and areas of focus. This section
 describes this complex state of affairs in terms of the
@@ -97,7 +97,7 @@ all types of API users:
 
 * Define functions and call them
 * Create classes and instantiate them
-* Create instances of builtin and user defined types
+* Create instances of builtin and user-defined types
   and perform operations on them
 * Introspect objects, including types, instances, and functions.
 * Raise and handle exceptions
@@ -108,7 +108,7 @@ all types of API users:
 
 The following sections look at the unique requirements of various stakeholders.
 
-Extension writers
+Extension Writers
 -----------------
 
 Extension writers are the traditional users of the C API. Their requirements
@@ -123,9 +123,9 @@ Applications with an embedded Python interpreter. Examples are
 
 They need to be able to:
 
-* Configure the interpreter (import paths, inittab, sys.argv, ...)
+* Configure the interpreter (import paths, inittab, ``sys.argv``, etc.).
 * Interact with the execution model and program lifetime, including
-  clean interpreter shutdown and restart
+  clean interpreter shutdown and restart.
 * Represent complex data models in a way Python can use without
   having to create deep copies.
 * Provide and import frozen modules.
@@ -178,7 +178,7 @@ and lower stability guarantees. Then the developers and users of
 these tools can choose whether to generate code that uses the
 faster or the safer and more stable version of the API.
 
-Binding generators
+Binding Generators
 ------------------
 
 Libraries that create bindings between Python and other object models,
@@ -203,7 +203,7 @@ They need to:
 * Adapt external mechanisms, execution models and guarantees to the
   Python way (green threads/continuations, one-writer-or-multiple-readers
   semantics, virtual multiple inheritance, 1-based indexing, super-long
-  inheritance chains, goroutines, channels, ...)
+  inheritance chains, goroutines, channels, etc.).
 
 Strengths of the C API
 ======================
@@ -236,7 +236,8 @@ C API problems
 ==============
 
 The remainder of this document summarizes and categorizes the problems that were reported on
-the [`capi-workgroup <https://github.com/capi-workgroup/problems/issues/>`__] repository. The issues are grouped into nine categories:
+the `capi-workgroup <https://github.com/capi-workgroup/problems/issues/>`__ repository.
+The issues are grouped into nine categories:
 
 - API Evolution and Maintenance
 - API Specification and Abstraction
@@ -313,7 +314,7 @@ occurs in the stable ABI as in the case of ``ob_refcnt`` and ``ob_type``,
 which are accessed via the reference counting macros
 [`Issue 45 <https://github.com/capi-workgroup/problems/issues/45>`__].
 
-A deeper issue was identified in relation to the way that reference
+We identified a deeper issue in relation to the way that reference
 counting is exposed. The way that C extensions are required to
 manage references with calls to ``Py_INCREF`` and ``Py_DECREF`` is
 specific to CPython's memory model, and is hard for alternative
@@ -379,7 +380,7 @@ initialized tuple, should also be removed (tuples are immutable
 once fully initialized)
 [`Issue 56 <https://github.com/capi-workgroup/problems/issues/56>`__].
 
-A few issues were identified with type definition APIs. For legacy
+We identified a few issues with type definition APIs. For legacy
 reasons, there is often a significant amount of code duplication
 between ``tp_new`` and ``tp_vectorcall``
 [`Issue 24 <https://github.com/capi-workgroup/problems/issues/24>`__].
@@ -399,7 +400,7 @@ on the thread state (in global scope). The design intention was that each
 API function returns a value indicating whether an error has occurred (by
 convention, ``-1`` or ``NULL``). When the program knows that an error
 occurred, it can fetch the exception object which is stored in the
-error indicator. A number of problems were identified which are related
+error indicator. We identified a number of problems which are related
 to error handling, pointing at APIs which are too easy to use incorrectly.
 
 There are functions that do not report all errors that occur while they
@@ -551,8 +552,8 @@ reliable
 
 **Naming**
 
-``PyLong`` and ``PyUnicode`` use names which don't match the python
-types they represent (int/str). This can be fixed in a new API
+``PyLong`` and ``PyUnicode`` use names which don't match the Python
+types they represent (``int``/``str``). This can be fixed in a new API
 [`Issue 14 <https://github.com/capi-workgroup/problems/issues/14>`__].
 
 There are identifiers in the API which are lacking a ``Py``/``_Py``