docs: copy edits across docstrings, comments, and tests - #418
Merged
Conversation
The previous round (DOI-USGS#417) covered the ADRs, guides, and glossary. This one extends the same copy editing to every .py file -- module and function docstrings, inline comments, and message strings -- and makes a further pass over the prose DOI-USGS#417 touched, so the source and the documentation use the same words for the same things. Figurative phrasing is replaced with the literal statement: - settings, not dials or knobs; parameters, not switches - "time without data" for the stall condition, not silence - "server-specified" for a Retry-After wait, not sanctioned or named - "is raised as", not surfaces; "is emitted", not fires - "without an error" or "undetected", not silently or quietly - "is defined in", not lives in; "run" a fan-out, not drive one - "takes precedence" and "outranks", not wins or beats - literal verbs where code was said to know, want, ask, answer, or trust - emphasis adverbs dropped where they carried no fact The glossary's terms are unchanged: leaf, facade, seam, fan-out, chunk, page walk, dialect, rung and ladder, no-progress budget, and the rest of CONTEXT.md. Test function names, fixture data, and quoted upstream text are untouched. The show_configuration sample output is duplicated in three places -- a docstring, the printed string, and the configuration guide -- and a test compares them, so all three were edited together. No behavior change. An AST comparison over all 81 changed Python files confirms only docstrings, comments, and message text differ; ruff, mypy --strict, and the offline suite pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N1Ap36zDGnifU8GvjnFowm
thodson-usgs
marked this pull request as ready for review
September 8, 2026 13:43
Collaborator
Author
|
@ehinman, this PR consists of one-or-two-word copy edits making the documentation more literal. No code changes |
thodson-usgs
added a commit
to thodson-usgs/dataretrieval-python
that referenced
this pull request
Sep 9, 2026
Two conflicts, both from main's copy-edit passes (DOI-USGS#417, DOI-USGS#418) landing on lines this branch had already rewritten: - NEWS.md: main added the 09/01 survey announcement at the top and reworded the 08/27 peaks entry; this branch added the 08/30 ratings entry. Kept all three, newest first, with main's wording of 08/27. - tests/nwis_test.py: main copy-edited the docstring of test_named_replacement_exists_in_waterdata, which this branch had replaced with the stronger test_named_replacement_resolves (ARG001 -- the old test never used its `name` parameter). Kept the replacement and carried main's edits into its docstring. Gates on the merged tree: ruff check + ruff format --check clean at the pinned 0.16.5, mypy --strict clean over 60 files, 1153 tests pass, coverage 98.93%, xenon / complexipy / import-linter (8/8) pass.
thodson-usgs
added a commit
to thodson-usgs/dataretrieval-python
that referenced
this pull request
Sep 9, 2026
The merge resolved that file with ``git checkout --ours``, which takes the whole ours-side blob rather than the one conflicted region, so everything main brought to the file was reverted: - ``TestReadRdb::test_malformed_peaks_frame_still_raises``, the regression test from DOI-USGS#344 -- the suite went 1154 -> 1153 and nothing flagged it, since a missing test cannot fail. - 36 lines of copy edits from DOI-USGS#417 and DOI-USGS#418, the passes that replaced figurative wording with literal ("has no opinion about it" -> "does not record it", "borrowing" -> "importing"). Redone as a three-way merge of the file with only the conflicted region resolved by hand. That region is main's copy edit of ``test_named_replacement_exists_in_waterdata``, a test this branch had already replaced with the stronger ``test_named_replacement_resolves`` (ARG001: the old one never read its ``name`` parameter). The replacement stands, with main's edits carried into its docstring -- the "Tripwire:" prefix and the contraction dropped, matching the pass that removed the only other instance of each in ``tests/``.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A second copy editing round. #417 covered the ADRs, guides, and glossary; this one extends the same editing to every
.pyfile — module and function docstrings, inline comments, and message strings — and makes a further pass over the prose #417 touched, so the source and the documentation use the same words for the same things.What changed
Figurative phrasing replaced with the literal statement:
Emphasis adverbs that carried no fact are dropped: actually, genuinely, precisely, merely, really, and "exactly" where it was not a count. Capitals used for emphasis are lowercased.
What is unchanged
The glossary's terms stay as
CONTEXT.mddefines them: leaf, facade, seam, fan-out, chunk, page walk, dialect and its quirks, rung and ladder, roster, horizon, no-progress budget with its spend and credit vocabulary, throttle, gate. Standard technical words stay too: driver, backoff, jitter, semaphore, hot path, warm cache, wall clock, drift, stale, leak, in flight. Test function names, fixture data, and quoted upstream text are untouched.Notes for review
show_configurationsample output is duplicated in three places — a docstring, the printed string, and the configuration guide — andtest_show_configuration_sample_output_is_currentcompares them. All three were edited together.transport/links.py, and the numeric-filter remedy inogc/filters.py. Both are covered by tests.Verification
An AST comparison over all 81 changed Python files confirms that only docstrings, comments, and string literals differ — no structural code change.
ruff check,ruff format --check,mypy --strict,lint-imports,xenon,complexipy, and the offline suite (1140 passed) all pass.🤖 Generated with Claude Code
https://claude.ai/code/session_01N1Ap36zDGnifU8GvjnFowm