[doc] standardize all lib/* READMEs + add a dogfooding doc-coverage gate#160
Merged
Conversation
Rewrites all 18 lib/* module READMEs to one standard (CLAUDE.md "Documentation standard"): title + purpose + capability profile, a scannable functions table up front (every script-visible member as a backtick token), constants/types tables, runnable examples ending in `# Output:`, and an explicit notes/boundaries section. The old framework-generated boilerplate (empty per-function Parameters tables, inconsistent style) is gone; the docs now read the same way and are easy for both humans and AI agents to parse. Adds a programmatic coverage gate. tools/doccov/coverage.star matches every member name against its README (as a backtick-quoted identifier); doc_coverage_ test.go enumerates the authoritative surface (each module's registered members across the Module/Struct/flat shapes) and runs the .star matcher through a Machine — so the check dogfoods the regex module. It runs in `make ci` via ./... (a missing member fails CI) and standalone via `make doc-check`. Baseline was 225/234; now 234/234 across 18 modules. (go.starlark.net-backed math/struct/ time have no lib README and are skipped.) Every runnable example was verified by execution. Fixes the inaccuracies that surfaced: re's collection outputs used single quotes (Starlark print renders strings inside collections with double quotes); file's read_bytes/trim_bom examples showed the `b"..."` repr instead of print's raw content; random's `print(0 <= val < 1)` used a chained comparison Starlark rejects at parse time; go_idiomatic claimed shared_dict supports iteration and the builtin `len()` (it supports neither — only the `.len()` method); stats documented covariance_population as 1.0 (it is 0.666…) and a stddev value off by its last digit, and listed sigmoid twice. The 9 members undocumented at baseline (http head + several try_*, go_idiomatic is_nil, json encode_indent) are now covered. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Up to standards ✅🟢 Issues
|
| Category | Results |
|---|---|
| CodeStyle | 100 minor |
🟢 Metrics 17 complexity · 0 duplication
Metric Results Complexity 17 Duplication 0
🟢 Coverage ∅ diff coverage · +0.00% coverage variation
Metric Results Coverage variation ✅ +0.00% coverage variation (-1.00%) Diff coverage ✅ ∅ diff coverage Coverage variation details
Coverable lines Covered lines Coverage Common ancestor commit (512d891) 7692 7277 94.60% Head commit (1f14ebb) 7692 (+0) 7277 (+0) 94.60% (+0.00%) Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch:
<coverage of head commit> - <coverage of common ancestor commit>Diff coverage details
Coverable lines Covered lines Diff coverage Pull request (#160) 0 0 ∅ (not applicable) Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified:
<covered lines added or modified>/<coverable lines added or modified> * 100%
NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #160 +/- ##
=======================================
Coverage 93.41% 93.41%
=======================================
Files 49 49
Lines 6177 6177
=======================================
Hits 5770 5770
Misses 258 258
Partials 149 149 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
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.
What
Two things, both about making the module docs trustworthy and keeping them that way:
Rewrote all 18
lib/*module READMEs to one standard (now recorded inCLAUDE.md→ Documentation standard forlib/*READMEs). Each README now opens with title + purpose + capability profile, then a scannable functions table (every script-visible member as a backtick token), constants/types tables, runnable examples ending in# Output:, and an explicit notes/boundaries section. The old framework-generated boilerplate (empty per-function#### Parameterstables, inconsistent style) is gone — the docs read the same way and parse cleanly for both humans and AI agents.Added a programmatic coverage gate.
tools/doccov/coverage.starmatches every member name against its README (as a backtick-quoted identifier);doc_coverage_test.goenumerates the authoritative surface (each module's registered members across the Module/Struct/flat shapes) and runs the.starmatcher through aMachine— the check dogfoods theregexmodule. It runs inmake civia./...(a missing member fails CI) and standalone viamake doc-check.Baseline 225/234 → 234/234 across 18 modules. (go.starlark.net-backed
math/struct/timehave no lib README and are skipped.)Every example verified by execution
A throwaway harness extracted and ran every
# Output:example through a Machine and diffed actual vs documented. That surfaced — and this PR fixes — real inaccuracies that manual review had missed:reprintrenders strings inside collections with double quotesfileread_bytes/trim_bomshowed theb"..."reprprintof bytes shows raw content; examples rewritten to be unambiguousrandomprint(0 <= val < 1)go_idiomaticshared_dictsupports iteration + builtinlen().len()); verified by executionstatscovariance_populationshown as1.0; a stddev digit off;sigmoidlisted twice0.666…; fixed; de-duplicatedThe 9 members undocumented at baseline (
httphead+ severaltry_*,go_idiomaticis_nil,jsonencode_indent) are now covered.Verification
gofmt/vetclean;make doc-check→ 234/234; full-race -count=2 ./...green; the go1.19 floor (Docker) green (incl.TestDocCoverage). Docs-and-one-test change; no library code touched.