Proposed small tweaks to the text of PEP 561 (#467)

pep-0561.rst

@@ -99,19 +99,21 @@ easy as possible, packaging and distribution is done through existing
 frameworks.
 
 Package maintainers who wish to support type checking of their code MUST add
-a ``py.typed`` file to their package supporting typing. This marker is
+a marker file named ``py.typed`` to their package supporting typing. This marker applies
-recursive, if a top-level package includes it, all sub-packages MUST support
+recursively: if a top-level package includes it, all its sub-packages MUST support
 type checking as well. To have this file installed with the package,
 maintainers can use existing packaging options such as ``package_data`` in
 distutils, shown below.
 
 Distutils option example::
 
-    ...
+    setup(
-    package_data = {
+        ...,
-        'pkg': ['py.typed'],
+        package_data = {
-    },
+            foopkg': ['py.typed'],
-    ...
+        },
+        ...,
+        )
 
 For namespace packages, the ``py.typed`` file should be in the submodules of
 the namespace, to avoid conflicts and for clarity.
@@ -124,8 +126,8 @@ type information, it is preferred that the ``*.pyi`` stubs are alongside the
 corresponding ``*.py`` files. However, the stubs can also be put in a separate
 package and distributed separately. Third parties can also find this method
 useful if they wish to distribute stub files. The name of the stub package
-MUST follow the scheme ``pkg_stubs`` for type stubs for the package named
+MUST follow the scheme ``foopkg_stubs`` for type stubs for the package named
-``pkg``. The normal resolution order of checking ``*.pyi`` before ``*.py``
+``foopkg``. The normal resolution order of checking ``*.pyi`` before ``*.py``
 will be maintained.
 
 Third parties seeking to distribute stub files are encouraged to contact the
@@ -133,18 +135,18 @@ maintainer of the package about distribution alongside the package. If the
 maintainer does not wish to maintain or package stub files or type information
 inline, then a third party stub only package can be created.
 
-In addition, stub only distributions SHOULD indicate which version(s)
+In addition, stub-only distributions SHOULD indicate which version(s)
 of the runtime package are supported by indicating the runtime distribution's
-version(s) through normal dependency data. For example, if there was a
+version(s) through normal dependency data. For example, the
-stub package ``flyingcircus_stubs``, it can indicate the versions of the
+stub package ``flyingcircus_stubs`` can indicate the versions of the
-runtime ``Flyingcircus`` distribution supported through ``install_requires``
+runtime ``flyingcircus`` distribution it supports through ``install_requires``
-in distutils based tools, or the equivalent in other packaging tools.
+in distutils-based tools, or the equivalent in other packaging tools.
 
 
 Type Checker Module Resolution Order
 ------------------------------------
 
-The following is the order that type checkers supporting this PEP SHOULD
+The following is the order in which type checkers supporting this PEP SHOULD
 resolve modules containing type information:
 
 1. User code - the files the type checker is running on.
@@ -154,7 +156,7 @@ resolve modules containing type information:
    stubs to use, and patch broken stubs/inline types from packages.
 
 3. Stub packages - these packages can supersede the installed packages.
-   They can be found at ``pkg_stubs`` for package ``pkg``.
+   They can be found at ``foopkg_stubs`` for package ``foopkg``.
 
 4. Inline packages - if there is nothing overriding the installed
    package, and it opts into type checking, inline types SHOULD be used.