docs(repo): sixth whole-repo pass over the repository files (#1103)

.github/FUNDING.yml

@@ -1,9 +1,9 @@
 # Platforms behind the repository's sponsor button.
 #
 # Only the platforms actually configured are listed. GitHub's commented-out
-# roster of every other platform used to sit below, but those lines were
-# instructions to whoever adopted the file rather than configuration, and one of
-# them (`otechie`) is no longer a platform GitHub documents.
+# roster of every other platform is left out: those lines are instructions to
+# whoever adopts the file rather than configuration, and one of them
+# (`otechie`) is no longer a platform GitHub documents.
 
 github: jarryshaw
 patreon: jarryshaw

.github/coverage.toml

@@ -15,8 +15,8 @@
 #                thread method on a hung test (#1387).
 #   sigterm   -- installs a SIGTERM handler that saves the data. `patch =
 #                ["_exit"]` covers os._exit and atexit covers a clean exit, but
-#                nothing covered a signal, so a worker SIGTERMed during
-#                shutdown would leave no file -- one candidate for #1423, whose
+#                neither covers a signal, so without this a worker SIGTERMed
+#                during shutdown leaves no file -- one candidate for #1423, whose
 #                actual cause is not established. Does not help against
 #                SIGKILL -- execnet's post-timeout kill is `Popen.kill()` --
 #                which is why `tests/conftest.py` also saves at

.github/release.yml

@@ -50,18 +50,18 @@
 #     against).
 #   * `dependencies` sits second-to-last rather than first -- see below.
 #
-# `dependencies` used to be the first category, and its pull requests are
-# almost all bot noise, from pyup and Dependabot. Moving it down is a
+# `dependencies` ranks second-to-last, and its pull requests are almost all bot
+# noise, from pyup and Dependabot. Ranking it low rather than first is a
 # judgement call, not a data requirement: nothing in the overlaps above forces
 # its position relative to anything except `release` and `ci`, both of which
-# already rank ahead of it regardless of where it sits. The case for moving it
-# here: a future pull request that mixes a real change with a `dependencies`
+# already rank ahead of it regardless of where it sits. The case for ranking it
+# low: a future pull request that mixes a real change with a `dependencies`
 # label (say, a fix prompted by a dependency bump) surfaces under that real
 # category instead of being swallowed by bot noise -- which is also,
 # concretely, what keeps #22 ("New distribution [0.13.3.post2]",
 # ci+dependencies+release) filed under Release rather than Dependencies. The
-# case for leaving it first, as before: it keeps a high-volume, low-interest
-# category out of the way of everything else on a first read. This file takes
+# case for ranking it first: it keeps a high-volume, low-interest category out
+# of the way of everything else on a first read. This file takes
 # the former; flip its position in the list below if that judgement is wrong.
 #
 # `*` catches whatever matches none of the categories above -- nothing in the

.github/workflows/create-release.yml

@@ -44,8 +44,8 @@ concurrency:
 # all need ``github``: rejecting it leaves nothing tagged and nothing published.
 # ``TestGatedJobsDependOnGithub`` in tests/project/test_release_gates.py checks
 # the ``needs:`` closure. Do not add a reviewer elsewhere without re-examining
-# it: a reviewer on ``conda-tag`` with ``needs: [ version_check ]`` is the bug
-# #887 fixed, which tagged and committed to ``main`` before the Release was
+# it: a reviewer on ``conda-tag`` with ``needs: [ version_check ]`` is #887's
+# defect, which tags and commits to ``main`` before the Release is
 # approved. One shared ``release`` would publish PyPI and Anaconda, different
 # credentials and indexes, together; and PyPI cannot afford an unintended
 # publish, since an accepted version number cannot be reused (``skip-existing:
@@ -69,8 +69,8 @@ concurrency:
 # publishes without naming an environment.
 #
 # #888: each publisher reads its own evidence, never "the ``v*`` tag exists" --
-# the two diverge on a half-completed release, and the next run then skipped
-# every job and reported green. ``github`` still reads ``PCAPKIT_TAG_EXISTS``,
+# the two diverge on a half-completed release, and a run reading the tag would
+# skip every job and report green. ``github`` still reads ``PCAPKIT_TAG_EXISTS``,
 # since that tag is its own artefact; ``tag`` reads whether ``conda-<version>+0``
 # exists, ``pypi`` PyPI's file count, and ``conda`` Anaconda's aggregate count
 # (a cost saver) plus, per leg, its own distribution -- the correctness fix,
@@ -133,7 +133,7 @@ jobs:
   # ``filter`` defaults to ``latest``:
   # https://docs.github.com/en/rest/actions/workflow-jobs#list-jobs-for-a-workflow-run
   # ``updated`` is ``'false'`` only for a ``skipped`` job; anything else it cannot
-  # read leaves it unset, and ``version_check`` runs as before.
+  # read leaves it unset, and ``version_check`` runs as it otherwise would.
   #
   # The concurrency group reads only the event, so such a run still joins
   # ``main``'s group and can displace a run pending there. It releases nothing
@@ -602,8 +602,8 @@ jobs:
       # its own ``ktlo_*`` output above (test_python_matrix_tiers_1633.py).
       matrix: ${{ fromJSON(needs.version_check.outputs.PYTHON_PYPI) }}
     steps:
-      # #1634: this run's commit, not ``ref: v<version>``, which was whatever
-      # ``main`` had become by approval; the next step checks the tag names it.
+      # #1634: this run's commit, not ``ref: v<version>``, which is whatever
+      # ``main`` has become by approval; the next step checks the tag names it.
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -680,7 +680,7 @@ jobs:
       # alone, as a rebuild is not byte-identical; after a 502 an asset "may
       # leave an empty asset with a state of starter", which ``--clobber``
       # replaces. A missing release fails ("release not found") where the action
-      # created one on the default branch. ``conda`` runs the same script.
+      # creates one on the default branch. ``conda`` runs the same script.
       - name: Upload package to GitHub Release
         id: upload
         if: ${{ steps.publish.outcome == 'success' }}

.github/workflows/cron-conda.yml

@@ -779,7 +779,7 @@ jobs:
       # ``draft``, which unset inputs make the tag, "" and false (the
       # ``CoreInputs`` getters ``name``, ``body``, ``createdPrerelease`` and
       # ``createdDraft`` in src/Inputs.ts, read through its ``updated*``
-      # getters), so each bump wiped the release's name and notes. Each
+      # getters), so unguarded each bump wipes the release's name and notes. Each
       # ``omit*DuringUpdate`` leaves its field undefined (the same ``updated*``
       # getters), and Octokit drops it (@octokit/endpoint's
       # ``removeUndefinedProperties``, called from its ``merge``, bundled in

.github/workflows/cron-vendor.yml

@@ -9,7 +9,7 @@ on:
   schedule:
     - cron: '0 10 * * 6' # Saturdays at 10:00 UTC
   # No `push` trigger: Unit Tests' own push run already reaches a verdict, and
-  # calling it again with `gate-only: true` re-ran the gate on the same tree
+  # calling it again with `gate-only: true` would re-run the gate on the same tree
   # (#715). `workflow_run` also fires for a pull request's run; the
   # `vendor-update` job's `if` refuses those, not a `branches:` filter here.
   workflow_run:

.github/workflows/experimental.yml

@@ -8,8 +8,8 @@ name: Experimental Tests
 # up nothing (#2030); it has no `workflow_call` trigger, and a job cannot
 # `needs:` one in another workflow.
 #
-# Its check names, `Python <version> (experimental)`, are the ones the legs had
-# in unit-tests.yml, and `windows`'s is `Python <latest> on Windows
+# Its check names, `Python <version> (experimental)`, follow unit-tests.yml's
+# `Python <version>` form, and `windows`'s is `Python <latest> on Windows
 # (experimental)` (#2060); no required context of ruleset 23497679 names one.
 #
 # The same events and `changes` job as unit-tests.yml, so a docs-only pull
@@ -613,7 +613,7 @@ jobs:
           retention-days: 7
 
   # #2060: the unit tier on Windows, the platform of the win-64 conda package,
-  # added so that its first release had a test run. One leg, on `latest`, the
+  # so that its releases have a test run. One leg, on `latest`, the
   # newest CPython the conda builds target. Non-blocking by `experimental`'s
   # mechanics: every step that can fail is `continue-on-error`, the long ones
   # have caps under the job's, `Experimental summary` reports each failure as a

.github/workflows/lint.yml

@@ -14,11 +14,11 @@ name: "Lint"
 # one tree disagree on it; a change in the R class alone is not evidence.
 #
 # Promotion order, cheapest first:
-#   * bandit -- clean since #2145: each finding was a false positive and carries
+#   * bandit -- clean (#2145): each finding was a false positive and carries
 #     a justified `# nosec`. Promotable.
-#   * vermin -- clean since #2145: meets vermin.ini's 3.8 target. Promotable.
-#   * mypy -- #2145 cleared the `unused-ignore`s and the pyshark link-type
-#     tables; the rest is real typing work.
+#   * vermin -- clean (#2145): meets vermin.ini's 3.8 target. Promotable.
+#   * mypy -- the `unused-ignore`s and the pyshark link-type tables are clean
+#     (#2145); the rest is real typing work.
 #   * pylint -- not realistically promotable: `unused-argument`,
 #     `redefined-builtin` and `super-init-not-called` are inherent to the
 #     schema DSL, and its metaprogramming yields `unsubscriptable-object` and
@@ -73,7 +73,7 @@ jobs:
           python-version: ${{ steps.python-versions.outputs.latest }}
 
       # `.[all,dev]`: pylint and mypy resolve imports, and `dev` carries the
-      # engines #910 took out of `all`. pylint's `import-error` for `pypcap` and
+      # engines `all` leaves out (#910). pylint's `import-error` for `pypcap` and
       # `pypcapfile` (`python_version < '3.12'`) and `pcap-ct` (in no extra
       # installed here) is expected.
       - name: Install package and lint tools

.github/workflows/python-compatibility.yml

@@ -50,7 +50,7 @@ jobs:
     # 23497679's required contexts. A KTLO leg is suffixed ` (KTLO)`, so no
     # required context can match it, and its steps carry `continue-on-error`,
     # as in unit-tests.yml's `test` job: job-level, a failed leg's check run
-    # concluded `failure`, so every commit showed red (#1672). Nothing below
+    # concludes `failure`, so every commit shows red (#1672). Nothing below
     # `requires-python`'s 3.8 runs (#2051).
     name: Compat Python ${{ matrix.python-version }}${{ matrix.ktlo && ' (KTLO)' || '' }}
     needs: [python-versions]

.github/workflows/unit-tests.yml

@@ -558,8 +558,8 @@ jobs:
   #
   # Scoped out (#845): per-engine integration coverage, which needs regenerated
   # captures and stays in aggregate in `integration` and `pypcap-parity`, and
-  # the multi-engine HAS_RUNTIME gate. #1538 dropped the DPKT cell, which ran
-  # only what `test` runs.
+  # the multi-engine HAS_RUNTIME gate. There is no DPKT cell (#1538): it would
+  # run only what `test` runs.
   engine-tests:
     name: Engines (${{ matrix.engine }})
     if: ${{ inputs.gate-only != true && needs.changes.outputs.code != 'false' }}
@@ -605,15 +605,15 @@ jobs:
       # `not-installable` ones too, so their failure is a genuine compile
       # failure rather than no compiler.
       #
-      # #974: an apt stall used to eat the whole job, whose cap reports
+      # #974: an unbounded apt stall eats the whole job, whose cap reports
       # `cancelled` and so fails `Required checks passed`. Not `-o
       # Acquire::Retries=3 -o Acquire::http::Timeout=30`, which #974 proposed:
       # both are noble's defaults already, and that per-`select()` timeout never
       # fires on a mirror that trickles. Hence `timeout(1)` around each apt
       # command: 60s update, 180s install (#1306), two attempts, inside the
       # 10-minute step cap, which stays the hang detector.
       #
-      # #1432: a slow mirror, not a dead one, then killed both attempts. So:
+      # #1432: a slow mirror, not a dead one, can kill both attempts. So:
       #
       # * **The .deb files are cached**, so a warm run downloads nothing. The
       #   key is a digest of the `Inst` lines of `apt-get install -s` -- every
@@ -704,7 +704,7 @@ jobs:
       # its extra, the others as the raw distribution, bypassing the marker
       # that would otherwise skip it silently (#845 finding 2). `set +e` covers
       # only that install; the pip upgrade and the `test` extra run under
-      # `set -eu`, as a broken base install once read as "expected" (#845).
+      # `set -eu`, as a broken base install would otherwise read as "expected" (#845).
       - name: Write the per-cell script
         run: |
           cat > "$RUNNER_TEMP/engine-cell.sh" <<'CELL'
@@ -939,7 +939,7 @@ jobs:
       # only place tests/integration/test_engine_runtime.py's real
       # ``engine='pyshark'`` extraction is reachable. Without tshark the engine
       # declines, the extractor silently falls back to the default parser, and
-      # the test used to pass on that fallback's output.
+      # the test passes on that fallback's output.
       #
       # The apt steps are `engine-tests`'s, for the reasons in the note above
       # its plan step, with APT_SET keeping this job's cache entries apart; this
@@ -1120,8 +1120,8 @@ jobs:
   # #1029: the protocols cell took 30.4 minutes of the 45-minute cap, so it is
   # split into `protocols/internet` and the rest (`protocols` with `--exclude
   # protocols/internet`), measured on CI at 8.2m and 7.6m. The cost: a pair of
-  # modules split between the two no longer shares a process, so pollution
-  # between them is invisible again; every pair of a protocols module followed
+  # modules split between the two does not share a process, so pollution
+  # between them is invisible; every pair of a protocols module followed
   # by a root-level module survives. The modules directly in tests/protocols
   # stay in the rest cell, as moving them would split more pairs than it joins.
   #
@@ -1133,10 +1133,6 @@ jobs:
   #     files, so the leg would run the root-level modules alone -- green,
   #     while covering none of it.
   #
-  # tests/corekit was once left out as permanently red; #2115 found its
-  # failures were test modules mixing two pcapkit imports, fixed them, and
-  # added the leg.
-  #
   # The `project` cell keeps the project pins (#1954): whether a module passes
   # in one interpreter, in file order, with no xdist, is a question about the
   # module, so a pin can fail it as readily as any other.
@@ -1154,7 +1150,7 @@ jobs:
     runs-on: ubuntu-latest
     # 45, as `test`'s: this is the only test job with no xdist, so a cell
     # carries its whole serial cost, and a contended run once passed 20
-    # minutes. The slowest cell since #1029 is 8.2m; even #1029's slowdown
+    # minutes. The slowest cell, with #1029's split, is 8.2m; even #1029's slowdown
     # window, at least 1.6x, leaves it far inside the cap.
     timeout-minutes: 45
     strategy:

CONTRIBUTING.md

@@ -178,16 +178,15 @@ review round.
 
 We follow a rough convention designed to answer two questions: what changed and why. The subject
 line carries the what, and the body of the commit describes the why. A real one from the history,
-with its body abridged:
+with its body abridged and its line anchors replaced by names:
 
 ```
 fix(tcp): resolve the connection flags before building the options (#587) (#597)
 
 Building any MP_JOIN option raised `AttributeError: 'TCP' object has no
-attribute '_flags'`. `TCP.make` built the options at tcp.py:547 and assigned
-`self._flags` only at tcp.py:567, but `_make_mptcp_join` (tcp.py:2780-2786)
-branches on that attribute to choose between RFC 8684 s3.2's three MP_JOIN
-layouts [...]
+attribute '_flags'`. `TCP.make` built the options before it assigned
+`self._flags`, but `_make_mptcp_join` branches on that attribute to choose
+between RFC 8684 s3.2's three MP_JOIN layouts [...]
 ```
 
 The format is:

MANIFEST.in

@@ -17,11 +17,8 @@ prune temp
 prune typings
 
 # Belt-and-braces, both of them: setuptools ships these two whether or not this
-# file mentions them, so neither line is load-bearing. An earlier version of this
-# comment claimed the opposite -- that ``include README.md`` was "the only thing
-# that puts it in an sdist" and that an sdist without it "cannot be installed at
-# all" -- and both halves are false. Measured by deleting the two ``include``
-# lines below and rebuilding from a clean tree: the ``tar tzf`` listing is
+# file mentions them, so neither line is load-bearing. Measured by deleting the
+# two ``include`` lines below and rebuilding from a clean tree: the ``tar tzf`` listing is
 # identical either way, with an empty ``diff``, and the resulting sdist
 # installs with exit 0. ``README.md``, ``LICENSE``, ``CHANGELOG.md`` and
 # ``CITATION.cff`` are all still in it.
@@ -34,7 +31,7 @@ prune typings
 #   (``setuptools/_distutils/command/sdist.py``) appends the first of those
 #   that exists to the file list unconditionally, before ``MANIFEST.in`` is read.
 #   The ``.md`` entry is setuptools' own addition over the distutils default, so
-#   the README becoming Markdown is exactly what this line stopped mattering for.
+#   it is what ships a Markdown README without this line.
 # * ``Distribution._finalize_license_files`` (``setuptools/dist.py``) supplies
 #   the default ``license_files`` glob
 #   ``['LICEN[CS]E*', 'COPYING*', 'NOTICE*', 'AUTHORS*']``, used because
@@ -48,9 +45,9 @@ prune typings
 # So the failure mode is real in principle; it just cannot be reached by removing
 # this line, because the README is in the sdist regardless.
 #
-# Of the ``include`` lines this file originally carried, only
-# ``include CHANGELOG.md`` is load-bearing: deleting it alone drops just that
-# file from the listing, and nothing else changes.
+# Of these two and ``include CHANGELOG.md`` below, only the last is
+# load-bearing: deleting it alone drops just that file from the listing, and
+# nothing else changes.
 #
 # These two are kept anyway, as an explicit statement of intent that does not
 # depend on a setuptools default staying where it is -- a much weaker reason than
@@ -96,5 +93,5 @@ recursive-include docs/source/changelog *.rst
 # straight from the tree, so the conda recipe builds no sdist; its modules
 # reach that wheel through package discovery, and every other file under it
 # through the ``package-data`` entry in ``pyproject.toml`` (#1814). A line naming
-# it would warn in every other build, and ``include`` of a directory matched
+# it would warn in every other build, and ``include`` of a directory matches
 # nothing even in the conda one (#1794).