Sweep the prose across docstrings, code comments, Sphinx .rst, the markdown docs, and the changelog for clarity, accuracy, and — the main point — concision.
Do this last. It touches nearly every file, so it will conflict with anything still open. It should start only once the other open issues are closed and the PR queue is empty.
What to fix
Cut length. Prefer the shortest statement that is still precise. Drop restatement, hedging, and background a reader does not need at that point. A docstring should say what a thing is, what it takes, and what it returns.
Keep design decisions. Concision is not an excuse to delete rationale. Where a choice was deliberate and a reader would otherwise undo it — why this type, why this guard, why this option was rejected — that reasoning stays. Tighten how it is written, do not remove it.
Cut timed context. Documentation should describe what the code does now, not when or why it changed. Remove references to when something was added, which PR or issue changed it, what it used to do, and how long a state has persisted. Version-bounded prose is the exception and stays: changelog entries, breaking-change notes, deprecation windows, and .. versionadded:: / .. versionchanged:: directives.
Keep accuracy. Where prose and code disagree, the code wins; fix the prose. Counts, line references, and type names are the usual offenders and rot silently.
The changelog needs this too
docs/source/changelog/1.5.0.rst entries have grown to paragraph length, several carrying full narrative rationale. They are legitimately time-bound, so the timed-context rule above does not apply to them — but the concision rule does. An entry should say what changed and what the effect is; the investigation behind it belongs in the issue, not the entry.
Root CHANGELOG.md is generated from the .rst by python util/changelog_md.py and must never be hand-edited — shorten the source and regenerate.
Scope
pcapkit/** docstrings and commentsdocs/source/**/*.rstdocs/source/changelog/** — concision only, not timed contextREADME.rst, CONTRIBUTING.md, and the other root documentstests/** comments, where they explain intent
Out of scope: root CHANGELOG.md as a direct edit target (regenerate it instead); pcapkit/const/** and pcapkit/vendor/** docstrings generated from IANA registries; verbatim ports of upstream code.
Approach
Split by directory into separate PRs. A single sweep across the whole tree is unreviewable, and the diff will be large even per-directory. The changelog is its own PR, and must not be folded into #657 — that PR is about accuracy and is close to merging.
Sweep the prose across docstrings, code comments, Sphinx
.rst, the markdown docs, and the changelog for clarity, accuracy, and — the main point — concision.Do this last. It touches nearly every file, so it will conflict with anything still open. It should start only once the other open issues are closed and the PR queue is empty.
What to fix
Cut length. Prefer the shortest statement that is still precise. Drop restatement, hedging, and background a reader does not need at that point. A docstring should say what a thing is, what it takes, and what it returns.
Keep design decisions. Concision is not an excuse to delete rationale. Where a choice was deliberate and a reader would otherwise undo it — why this type, why this guard, why this option was rejected — that reasoning stays. Tighten how it is written, do not remove it.
Cut timed context. Documentation should describe what the code does now, not when or why it changed. Remove references to when something was added, which PR or issue changed it, what it used to do, and how long a state has persisted. Version-bounded prose is the exception and stays: changelog entries, breaking-change notes, deprecation windows, and
.. versionadded::/.. versionchanged::directives.Keep accuracy. Where prose and code disagree, the code wins; fix the prose. Counts, line references, and type names are the usual offenders and rot silently.
The changelog needs this too
docs/source/changelog/1.5.0.rstentries have grown to paragraph length, several carrying full narrative rationale. They are legitimately time-bound, so the timed-context rule above does not apply to them — but the concision rule does. An entry should say what changed and what the effect is; the investigation behind it belongs in the issue, not the entry.Root
CHANGELOG.mdis generated from the.rstbypython util/changelog_md.pyand must never be hand-edited — shorten the source and regenerate.Scope
pcapkit/**docstrings and commentsdocs/source/**/*.rstdocs/source/changelog/**— concision only, not timed contextREADME.rst,CONTRIBUTING.md, and the other root documentstests/**comments, where they explain intentOut of scope: root
CHANGELOG.mdas a direct edit target (regenerate it instead);pcapkit/const/**andpcapkit/vendor/**docstrings generated from IANA registries; verbatim ports of upstream code.Approach
Split by directory into separate PRs. A single sweep across the whole tree is unreviewable, and the diff will be large even per-directory. The changelog is its own PR, and must not be folded into #657 — that PR is about accuracy and is close to merging.