Skip to content

docs: document doctor finding codes; correct the B-frame conformance claim - #56

Closed
chintondutta wants to merge 1 commit into
Hebbian-Robotics:mainfrom
chintondutta:docs/10-doctor-finding-codes-and-bframe-claim
Closed

docs: document doctor finding codes; correct the B-frame conformance claim#56
chintondutta wants to merge 1 commit into
Hebbian-Robotics:mainfrom
chintondutta:docs/10-doctor-finding-codes-and-bframe-claim

Conversation

@chintondutta

Copy link
Copy Markdown
Contributor

Fixes #10.

Two gaps

1. docs/FORMAT.md claimed a check the doctor doesn't perform. Conformance item 4 stated "no B-frames" as part of what hflow doctor checks. src/hflow/doctor.py verifies the h264 format, AUD-delimited access units, SPS/PPS on keyframes, and keyframe-first ordering -- but has no B-frame detection. Reworded the item to keep no-B-frames as a stated convention (linked to the existing "In-band video" section that already documents it) while being explicit that the doctor doesn't check it yet.

2. The doctor's finding codes were documented nowhere. Finding.code is declared a "stable kebab-case identifier" but no page listed them. Enumerated all 16 by grepping collector.add( in doctor.py (the issue estimated ~14; there are 16) and added a table under a new "Doctor finding codes" section in docs/FORMAT.md: code, level, one-line meaning, matching each call site's actual message.

Docs only, no code changes.

Testing

docker run --rm -v "$PWD:/data" -w /data lycheeverse/lychee:latest --no-progress --include-fragments \
  --exclude '^https://github\.com/Hebbian-Robotics/hflow/(issues|security/advisories/new)$' \
  --exclude-path references/mcap-spec.md \
  --exclude-path references/foxglove-CompressedVideo.proto .
# 231 Total, 0 Errors

uv run pytest -q       # 297 passed, 3 skipped; unrelated: tests/test_ffmpeg.py fails/errors in this sandbox (no ffmpeg/ffprobe on PATH)
uv run ruff check --fix
uv run ruff format
uv run ty check

(lychee wasn't on PATH in this sandbox; ran it via the official Docker image instead of installing.)

…claim

FORMAT.md's conformance item 4 implied hflow doctor checks for B-frames --
it doesn't (no B-frame detection exists in doctor.py); marked it a
convention not yet checked. Added a table of all 16 finding codes emitted
by doctor.py (grepped collector.add(...) call sites to enumerate them),
each with its level and meaning, since Finding.code is documented as a
stable identifier but was listed nowhere.
@github-actions

Copy link
Copy Markdown

👋 Hi @chintondutta — thanks for the contribution! To keep starter issues available
for other contributors and give every pull request a real review, we accept
1 open pull request per contributor at a time.

You already have #52 open, so this one is being closed automatically.
Once your open pull request is merged or closed, feel free to reopen this one —
no work is lost.

@github-actions github-actions Bot closed this Aug 20, 2026
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.

Docs: document the doctor finding codes; FORMAT.md claims a B-frame check that does not exist

1 participant