Brane Documentation (Post-Implementation)

Golden Rule: Documentation that misleads is worse than no documentation.

When to Use

Invoke /brane-docs after completing implementation that affects:

• •New public classes, methods, or types
• •Changes to existing public API behavior
• •New features users need to know about

Workflow

1. Identify What Changed

git diff --name-only HEAD~1 | grep '\.java$'

Focus on public API changes in:

• •brane-core/src/main/java/sh/brane/core/...
• •brane-rpc/src/main/java/sh/brane/rpc/...
• •brane-contract/src/main/java/sh/brane/contract/...

2. Update Javadoc

Update source files directly. Required elements:

• •Summary sentence (imperative: "Sends", "Creates", "Binds")
• •@param for every parameter (state nullability)
• •@return for non-void (state empty/null semantics)
• •@throws for all exceptions (state condition)
• •Working {@code} examples for public entry points

3. Update Website Docs

Docs location: website/docs/pages/docs/

website/docs/pages/docs/
├── quickstart.mdx
├── architecture.mdx
├── performance.mdx
├── reader/           # Brane.Reader methods
│   ├── api.mdx
│   ├── simulate.mdx
│   └── subscriptions.mdx
├── signer/           # Brane.Signer methods
│   ├── api.mdx
│   ├── signers.mdx
│   ├── hd-wallets.mdx
│   ├── eip712.mdx
│   ├── blobs.mdx
│   └── custom-signers.mdx
├── contracts/
│   ├── bindings.mdx
│   ├── interaction.mdx
│   └── multicall.mdx
├── testing/          # Brane.Tester methods
│   ├── overview.mdx
│   ├── setup.mdx
│   ├── state.mdx
│   ├── impersonation.mdx
│   ├── mining-time.mdx
│   └── accounts.mdx
├── providers/
│   ├── http.mdx
│   └── websocket.mdx
├── utilities/
│   ├── types.mdx
│   ├── abi.mdx
│   ├── errors.mdx
│   ├── threading.mdx
│   └── metrics.mdx
└── chains/
    └── profiles.mdx

4. Which Page to Update?

5. Evaluate CLAUDE.md Updates

After updating Javadoc and website docs, decide whether CLAUDE.md files need updates.

Update CLAUDE.md when:

• •New public class added that users will interact with → Add to "Key Classes" section
• •New usage pattern that differs from existing examples → Add to "Patterns" section
• •Discovered a gotcha or pitfall → Add to "Gotchas" section
• •Significant behavioral change that affects documented patterns

Skip CLAUDE.md when:

• •Minor method additions that follow existing patterns
• •Internal implementation changes
• •Bug fixes that don't affect documented behavior
• •Changes already well-represented by existing documentation

Which CLAUDE.md to update:

When updating, follow existing structure:

• •Key Classes: Brief description, key methods/purpose
• •Patterns: Working code examples with realistic scenarios
• •Gotchas: Specific class/method, clear issue, resolution

Accuracy Checklist

Before finishing, verify:

Javadoc:

• • Summary matches actual behavior (re-read implementation)
• • All parameters documented with correct types
• • All thrown exceptions listed
• • Example code actually works

Website Docs:

• • Code examples include imports
• • Method signatures match actual API
• • No stale examples from previous versions

Cross-Reference:

• • Javadoc and website docs say the same thing
• • No contradictions between sources

CLAUDE.md (if applicable):

• • Key classes table includes new public classes
• • Patterns section has working examples for new patterns
• • Gotchas are specific and actionable
• • Module-level and root CLAUDE.md are consistent