Remove documentation rot and tighten the prose - #98
Open
splch wants to merge 2 commits into
Open
Conversation
Prose that restates code is deleted, converted to a pointer at the source of truth, or pinned by tests/test_docs_consistency.py: - Fix drift that had already happened: CONTRIBUTING still said the post-hooks "run ruff fix-and-format" after the fix hook was removed. The hook enumeration there is now a pointer, and every hook in openapi-python-client-config.yaml carries its own explanatory comment. - exceptions' module example imported nothing and referenced an undefined payload; it now imports create_job and elides the body honestly. - Remove unpinned numeric copies: _transport's docstring no longer repeats the retry codes and backoff knobs (it names RETRYABLE_STATUS_CODES and build_transport instead); ClientExtension.retryable_status_codes points at the constant rather than enumerating it; "Defaults to DEFAULT_MAX_RETRIES (2)" drops the "(2)". - Remove rot-prone literals from AGENTS.md: the "Four have non-obvious behavior" workflow count and the fixture bullet's hardcoded token and test base URL. - New pins: IonQClient's user-facing defaults (retries, timeout read and connect) now track the constants; the setup-uv composite's hardcoded python-version default tracks .python-version; and every python code fence in README and the published docstrings (12 today) must parse, so example code can no longer rot silently.
Prose-only pass over comments, docstrings, and docs: delete what restates the code, tighten what stays, keep constraints and why-notes. No behavior change; generated files untouched.
This was referenced Aug 25, 2026
natestemen
approved these changes
Aug 26, 2026
natestemen
left a comment
natestemen
left a comment
Contributor
There was a problem hiding this comment.
LGTM. Did you tell an agent to use ASD-STE100 Simplified Technical English? I've seen that's all the rage nowadays.
Comment on lines
-150
to
+136
| max_retries: Maximum number of retry attempts. Defaults to | ||
| `DEFAULT_MAX_RETRIES` (2). | ||
| retryable_status_codes: HTTP status codes that trigger a retry. | ||
| Defaults to `RETRYABLE_STATUS_CODES`. | ||
| verify: TLS verification (``True``/``False``, a CA bundle path, or an | ||
| ``ssl.SSLContext``) applied to the underlying transports; httpx | ||
| ignores client-level ``verify`` when a custom transport is | ||
| supplied, so it must be configured here to take effect. | ||
|
|
||
| Returns: | ||
| A configured `ErrorRaisingTransport` ready to be passed to an | ||
| httpx client (sync or async). | ||
| verify: TLS verification (``True``/``False``, a CA bundle path, or an ``ssl.SSLContext``) | ||
| applied to the underlying transports. httpx ignores client-level ``verify`` when a | ||
| custom transport is supplied, so it must be set here to take effect. |
Contributor
There was a problem hiding this comment.
Looks like some of the argument descriptions got dropped. Was that intentional?
Contributor
There was a problem hiding this comment.
Might be worth a comment in this file about catching drift between docs and code, and also whatever writing style you recommended for the agent that made the changes in this PR.
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
2 participants
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.
Summary
Part 3 of the stack #96 -> #97 -> #98 -> #95; merge bottom-up (each PR targets the previous one's branch). Removes documentation rot and drift opportunities, then shortens the remaining prose.
exceptionsexample referenced an undefined name)._transport's docstring names constants instead of repeating retry numbers, AGENTS.md drops rot-prone counts and literals plus its drifted third copy of the regen command.test_docs_consistency.py: IonQClient's documented defaults, the setup-uv composite's Python default, the spec-driftSPEC_URL, and a new guard that parses every ```python fence in README and the published docstrings (12 today), so examples can no longer rot silently.pre-commitis not installed byuv sync; both docs now useuvx pre-commit.Test plan
uv run pytestat this head: 275 passed (new pins and the example parse guard included), 100% branch coverage, warnings-as-errors.uv run ruff check,uv run ruff format --check,uv run ty check ionq_core/: clean.pdocbuilds.Important
Most code in
ionq_core/is auto-generated and overwritten on regeneration.See CONTRIBUTING.md for which files are safe to edit.