Topic · documentation coverage

Documentation coverage

Gist

Documentation coverage is whether each requirement has a reviewable doc the audit can re-read. Proof inventories those with proof audit --check documentation_coverage. A Sphinx percent is not a documented_by row. Compodoc still owns the docstring bar. Jama still authors.

proof audit --check documentation_coverage

Keep Sphinx if you already measure API docstring coverage. Keep Compodoc if you already score Angular. Keep Jama if you author shalls. Proof will not count a percent as a documented_by row.

Request demo Last Sphinx percent vs this record

01 · The unsigned percent

A docstring bar is not a requirement doc.

You can merge a green suite and still have no file that explains the shall the audit can re-read.

The split is old. A coverage number on comments is a count of documented symbols. A documented_by row is a path the audit can open. The words are not severity. A man page that never names the requirement is still a comment file. A help topic that names the ID is still documentation even if nobody published a site.

The matrix of which requirement maps to which file lives on requirements traceability matrix. The writing rules for the shalls live on INCOSE and ASD-STE100. This page is the inventory of traces.documented_by: a real path under project.documentation.sources, or an honest miss. It is not a second RTM lecture.

proof audit --check documentation_coverage
proof trace coverage
proof trace autolink
proof help documentation_coverage

Until that review runs, the YAML can look complete and the docs can still be a comment percent. Nobody has said which file explains this shall, or whether the ID is in that file.

02 · The exhibit

Same shall. A percent, or a path.

The suite can stay green. The requirement still needs a file. Click the tabs.

Docstring bar

said 87% documented
path nobody named
req id not in the file

Suite still green

This push

No documented_by. No Documents comment. The merge still went green.

Unsigned percent

Docstring bar

Still a percent on symbols. Still not a requirement path. Keep Sphinx if you want. CI does not read it.

Keep the report

Proof

Check documentation_coverage
Link traces.documented_by
Marker

Missing path fails the check

Same shall. A percent, or a path. Click the tabs.

Surface	What they do	What Proof does	What we lose
Sphinx coverage	Counts documented Python modules and members.	Not this command. Proof does not score docstrings.	No Sphinx report. Keep Sphinx.
Compodoc / Swift-DocC	A percent of Angular or Swift API surface with comments.	Not a docstring bar. Proof stamps a path on a requirement YAML.	No Compodoc. No DocC flag.
coverage.py	Code coverage of Python tests. The SERP often lands here first.	Not this H1. Line coverage lives on test coverage vs requirements coverage.	No coverage.py. Wrong universe.
PageLoop “features with published docs”	A product KPI: share of features that have a help article.	Not a marketing score. Proof asks whether this shall has a file.	No feature KPI. No CMS.
documented_claim_verified	Named claims from man pages and godoc, bound to a symbol.	A different check. Opt-in. Skips until you author `documented_behaviors`.	Coverage is not claim verification.
documentation_enforced	Every shall must appear in one chosen artifact, such as a man page.	A narrower companion. Off until `documentation.enforce_sources` is set.	Default coverage is not a man-page gate.
Jama / DOORS	Author and store the programme, including attached documents.	Jama still authors. Proof holds the path as a file the audit can re-read. IBM DOORS stays a mention on Proof vs Jama.	Not an ALM. Jama still authors.

The teaching graph is still a requirement with a documented_by path. Autolink only writes that path from a deterministic marker. Front-matter related_requirements feeds CLI help. The HTML comment  is what proof trace autolink reads. Populate both, then run autolink. One without the other is a common miss.

proof trace autolink
proof trace coverage
proof trace suspect
proof audit --check documentation_coverage --verbose

If the only real prose lives under docs/internal/, that path must stay inside project.documentation.sources. Exclude it and the check reports the shall as undocumented even when reviewable prose already exists. A document that never names the ID is not inferred. Editing YAML to fake the row is a lie the next autolink will not save.

03 · The honest loss

Proof stamps the path. It does not write the manual.

A documented_by row is not a proof of the Go. Jama still authors.

Proof does not implement Sphinx, Compodoc, Swift-DocC, or coverage.py. It does not count comment lines. A passing documentation_coverage check means a named path exists under the configured sources. It is not a proof that the prose is true. It is not a proof that the Go matches the shall. It is not a docstring percent. We have not scored this against Sphinx or Compodoc on a frozen pack. The loss is named, not scored.

proof audit --check documented_claim_verified is a different command. That check is opt-in and skips until you author claims. Do not treat a clean coverage list as verified man-page promises.

The RTM H1 stays on requirements traceability matrix. Jama still authors.

Request demo How the install is bought

04 · Nearby questions

What people type next.

What is documentation coverage? Same question. Same URL.

Is this Sphinx documentation coverage? No. Sphinx still owns the docstring bar. Proof stamps a path on a requirement file.

Is this coverage.py? No. That is code coverage. The H1 lives on test coverage vs requirements coverage.

Is this documentation enforced? Only after you opt in. documentation_enforced is off until documentation.enforce_sources is set. Default coverage is the inventory, not the man-page gate.

Is Proof Compodoc? No. Jama still authors. Proof takes the authored shall and asks CI whether a reviewable file still names it.