Skip to content

docs(errors): document exception hierarchy and enrich Errors reference page#168

Merged
justinjoy merged 2 commits into
mainfrom
docs/errors-167
Jun 15, 2026
Merged

docs(errors): document exception hierarchy and enrich Errors reference page#168
justinjoy merged 2 commits into
mainfrom
docs/errors-167

Conversation

@justinjoy

Copy link
Copy Markdown
Contributor

Resolves #167.

Improves the Errors reference documentation in two atomic commits, produced via a consensus-gated implementation flow (architect+critic guidance → implementer → reviewer → architect+critic audit → consensus).

Changes

Unit 1 — 199372a — docstrings + presence test

  • Documents the 5 previously-undocumented exception classes (InvalidIRError, ExecError, WirelogIOError, CompoundSaturatedError, CompoundBusyError) and expands the terse ones; each cites its WIRELOG_ERR_* code and when it is raised.
  • ExecError documented as the catch-all (invalid args, closed/null handles, missing relations).
  • ParseError gains an Attributes: section for its best-effort line/column/source payload.
  • Fixes module-docstring miscount ("Two" → "Three" PyreWire-only exceptions).
  • Adds a self-discovering test asserting every WirelogError subclass in the module has its own non-trivial docstring.

Unit 2 — 8b9c152 — enrich docs/reference/errors.md

  • Intro overview, wirelog_error_t code→exception mapping table, a "PyreWire-only errors (not produced by check())" section, an exception-handling example (public imports), and ::: directives for check() / error_string().
  • All 11 per-class blocks preserved.

Accuracy

raised when descriptions cross-referenced against bundled wirelog 0.51.0 (0c6e0cd) and the real raise sites. The consensus audit corrected three docstring-accuracy defects before merge:

  • WirelogVersionError — described the wrong same-named class; corrected to the capability/symbol gate at program.py:163.
  • WirelogModeError — "insert batch" → session-level mode exclusivity (step/snapshot/query).
  • WirelogIOError — "via check()" → direct raise via io_adapter.py.

Verification

  • flake8 / black / isort clean; errors.py mypy clean
  • pytest: errors 27/27, full suite 91.24% coverage
  • mkdocs build --strict: passes (0 errors)

Follow-ups (non-blocking, out of scope)

  • WirelogInternError docstring documents reverse-intern lookup only, but intern.py:46 also raises on forward-intern failure (pre-existing).
  • Two distinct classes named WirelogVersionError (_core/errors.py vs _ffi/_loader.py) — consider consolidating.

Fill in docstrings for the exception hierarchy in pyrewire._core.errors:
the five previously-undocumented classes (InvalidIRError, ExecError,
WirelogIOError, CompoundSaturatedError, CompoundBusyError) and expand the
terse ones. Each states its WIRELOG_ERR_* code and when it is raised;
ExecError is documented as the catch-all (invalid args, closed/null
handles, missing relations). ParseError gains an Attributes section for
its best-effort line/column/source payload. Fix the module docstring
miscount (Two -> Three PyreWire-only exceptions).

Add a self-discovering test asserting every WirelogError subclass defined
in the module carries its own non-trivial (>=30 char) docstring.

Refs #167
Comment thread tests/test_errors.py

import pytest

import pyrewire._core.errors as _errors_module
@justinjoy justinjoy merged commit d397ada into main Jun 15, 2026
17 checks passed
@justinjoy justinjoy deleted the docs/errors-167 branch June 15, 2026 09:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Errors reference page is sparse: missing/terse docstrings in pyrewire._core.errors

1 participant