Repository navigation
docs: add style guide and bring docs, Javadoc and site into conformance - #178
Merged
Merged
Conversation
- Add docs/style.md (register, emphasis, headings, justification, punctuation and mechanics) and point CLAUDE.md at it. - Root Markdown (README, DESIGN, CONTRIBUTING, GETTING_STARTED, RELEASE, SECURITY, CHANGELOG, CLAUDE.md), docs/ (operator guide, stability, threat model, transactional semantics, ADRs), example and SDK READMEs, and site/index.html: third-person present tense, no stress emphasis, noun-phrase headings, no em dashes, serial comma, British spelling, 100-column wrap. Cross-references to renamed anchors updated. - Javadoc across all modules and TSDoc in the browser SDK: same rules, prose only; code, identifiers and tags unchanged. - Factual fixes found along the way: ChallengeId format and SPI ownership in DESIGN.md, demo persistence flags in GETTING_STARTED and the Dropwizard demo, migrations are host-run (site), missing [2.2.0] CHANGELOG link reference. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
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
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.
Summary
docs/style.mdand pointsCLAUDE.mdat it.docs/, ADRs, example and SDK READMEs),site/index.html, Javadoc in every module, and TSDoc in the browser SDK into line with the guide: third-person present tense, no stress emphasis, noun-phrase headings, no em dashes, serial comma, British spelling, 100-column wrap.{@code}/{@link}targets,@sincevalues and code blocks are unchanged. Renamed heading anchors had their cross-references updated; no external links into renamed anchors were found.ChallengeIdformat and SPI ownership in DESIGN.md, demo persistence switches (GETTING_STARTED, Dropwizard demo README and Javadoc), host-run migrations on the site, and the missing[2.2.0]CHANGELOG link reference.Test plan
./gradlew spotlessApply check(JDK 21) passesnpm run buildandnpm testpass (npm run typecheckfails identically onmain:Cannot find module '../dist/src')Open items for the maintainer
og-image.pngwas not regenerated; it still shows the old tagline (the SVG source is updated).1.xline, while releases are on 2.x.ttlfield onJwtClaimsthat does not exist.<em>/<b>styling on the site was kept because removing it needs CSS changes.//line comments and code-block comments were out of scope and still contain some em dashes.🤖 Generated with Claude Code