docs: stop offering an examples-local type, and drop the counts that keep rotting - #482
Merged
Conversation
…keep rotting The example catalogue introduced the cover letter as a `BusinessTheme.modern()` document. That record lives in the examples module and ships in no artifact, so a reader who adds the dependency and reaches for it finds nothing to import. The rows and prose now describe what the examples demonstrate; the advanced section that quotes the helper says it is examples-local and names `BrandTheme` as the shipping equivalent. ExamplesLocalTypeGuardTest bans the factory-call form on any README and leaves the fence alone — a fence quotes an example's own source, and editing the type out of a quotation would make it false. Four counts are removed rather than corrected: the catalogue was "~53 PDFs" with a "curated 39-PDF subset" where it generates 91 and commits 62, the banner caption stated a line count for the example it links, and it named the module graph by a version the image no longer shows. Each had been reconciled before. The commit-message examples pointed at the 1.5 line while the pull-request template requires a conventional subject and 26 of the last 30 commits are one.
…at misled The replacement sentence was as untrue as the one it replaced: it said the palette and fonts come from a record the example declares, and the example imports the shared examples-module helper and calls it. The section now says the colours come from a helper local to this module and names BrandTheme as the shipping equivalent. Three defects in the rule: - it matched any dot after the type name, so a markdown link to the type's own source would have failed the build citing a call that was never written. It now matches a call. - the bare name in a table row passed, which is the form the defect was actually written in. A row naming the type is now rejected too; elsewhere in prose the bare name stays legal, because these pages describe those examples. - one of the package's five types was listed. The set is read from the source tree, so the next helper is covered without anyone remembering this file. The guard-the-guard compared prose against a fixed floor that the fenced content clears on its own — an inverted split would have passed it. It compares the two halves instead.
…uotation The rule read one README per module and skipped every fenced block, which left the two forms most likely to mislead outside it: a nested page under docs/, and a tutorial snippet — the thing a reader copies rather than reads. - The scan covers the published documentation, historical records aside: pages under docs/adr, docs/archive, docs/migration, docs/roadmaps and the v1-classic templates exist to record what a past release contained, and the decision guide between the removed and layered surfaces names the old one beside its replacement on purpose. - Code blocks are scanned. The one exemption is a fence introduced by a doc-example-ignore marker, which already carries a written reason and is how a page quotes an example's own source verbatim. A test asserts that path is still exercised, so the escape hatch cannot quietly become dead code. - Construction, method references and member access join the call form. Three unguarded ways to make the same offer is not a rule. - An unclosed fence is caught per page. It exempts everything below it, and the totals cannot see one file going quiet. The entry describing the removed counts had itself acquired five of them, in a bullet titled "the last hardcoded counts are gone"; every figure that can drift before the release is out.
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.
Why
Three things in the reader's path said something the code does not.
The example catalogue's entry-point table introduced the cover letter as a
BusinessTheme.modern()document.BusinessThemeis a record incom.demcha.examples.support.theme— it ships in none of the published artifacts, and its ownpackage-infoalready says so. A reader who adds the dependency and reaches for it finds nothing to import, and finds that out only after the failed import.The catalogue named a count of generated documents and a count of committed previews. Both sat well below the real inventory, having been reconciled by hand once already and drifted again since.
The banner caption named "the 2.0 module graph" while the image it captions renders 2.1, and stated a line count for the example it links.
What
The examples-local type leaves the entry points. The Start here row and the section intro say what the example demonstrates; the section states that its colours come from a helper local to this module and names
BrandThemeas the shipping equivalent.ExamplesLocalTypeGuardTestpolices using the type, across the published documentation.Where it looks: every published page — the READMEs and the docs tree — minus the pages whose subject is what a past release contained (
docs/adr,docs/archive,docs/migration,docs/roadmaps,docs/templates/v1-classic) and the decision guide that names the removed surface beside its replacement on purpose. The same exemptions the canonical surface guard already uses, for the same reason.What it rejects: a call, a constructor, a method reference, a member access — three unguarded ways to make the same offer is not a rule. A member named
javais exempt, because that is a link to the type's own source rather than an API being suggested. The bare name stays legal in prose, since these pages have to name what they describe; in a table row it does not, because there a bare name is a claim about what that row's document is made of, which is how the defect was written.Code blocks are scanned. A fenced snippet is the most copy-pasted thing on a page, so exempting fences wholesale would leave the rule policing only the form nobody copies. The single exemption is a fence introduced by a
doc-example-ignoremarker, which already carries a written reason — and a test asserts that path is still exercised, so it cannot quietly become dead code.An unclosed fence fails per page. It exempts everything below it, and no aggregate can see one file going quiet.
The type set is read from the helper package rather than listed — five types today, and a list would have covered whichever one was noticed first.
Four counts are removed, not corrected. The CHANGELOG entry describing that had itself acquired five figures; those are out too.
Tests
qagate: 688 tests,BUILD SUCCESS. Core guard job as CI runs it: 35 tests,BUILD SUCCESS.docs/using itnew BusinessTheme(…)BusinessTheme::moderndoc-example-ignorefence quoting example source