tomevault-io /natspec
Generates NatSpec-style documentation comments for complex implementations in any language. Detects the file's language, adapts the comment syntax, and documents all public/exported declarations.
Reference
Read references/natspec-patterns.md for tag rules, format by language,
and examples before starting.
Flow
Step 1 — Identify the target
If the argument is a file → process only that file.
If the argument is a directory:
→ Glob for all source files recursively.
→ Ignore: node_modules/, dist/, build/, .git/, config files.
If no argument → ask the user: specific file or entire directory?
Step 2 — Detect language and mode
Language (by file extension):
| Extension | Language | Comment syntax |
|---|---|---|
.ts, .tsx |
TypeScript | /** ... */ (JSDoc) |
.js, .jsx |
JavaScript | /** ... */ (JSDoc) |
.sol |
Solidity | /// ... (NatSpec native) |
.py |
Python | """...""" (docstring) |
.rs |
Rust | /// ... (doc comments) |
.go |
Go | // ... (GoDoc) |
| Other | Generic | /** ... */ |
Mode (by current coverage):
| Situation | Mode |
|---|---|
| No documentation at all | full — document everything |
| Partial documentation | patch — complete what's missing |
| Fully documented | audit — validate only |
Step 3 — Execute in parallel
For each file in full or patch mode, spawn a natspec-writer:
Agent(
subagent_type: "natspec-writer",
prompt: "File: [path]. Language: [language]. Mode: [full|patch].
Read the file, generate NatSpec for all public/exported functions,
classes, interfaces, types, events, and errors.
Reference: .claude/skills/natspec/references/natspec-patterns.md"
)
Independent files run in parallel. One agent per file.
Step 4 — Validate in parallel
After all writers complete, spawn a natspec-validator per file:
Agent(
subagent_type: "natspec-validator",
prompt: "Validate NatSpec completeness in: [path]. Language: [language].
Reference: .claude/skills/natspec/references/natspec-patterns.md"
)
Step 5 — Consolidated output
NATSPEC COMPLETE
Files processed: N
✅ src/module/file.ts — 12 declarations documented, 0 issues
✅ contracts/Vault.sol — 8 declarations documented, 0 issues
⚠️ src/lib/api.ts — 5 declarations documented, 2 warnings
└─ Line 47: @returns missing description
└─ Line 89: @param has no description
Total: N functions | N classes | N types documented
Special cases
Private/internal functions:
→ @dev only — @notice is optional (not ABI/API public).
Inheritance / Override:
→ Override with no added logic: use @inheritdoc.
→ Override with added logic: document normally + mention the override.
Complex types (interfaces, enums, structs):
→ Document the type with @notice.
→ Document each field/member with inline @dev.
Async functions:
→ @returns must describe what the Promise resolves to, not the Promise itself.
Success Criteria
- All exported/public declarations have
@noticeand@param/@returns - Private functions have
@devwhen logic is non-obvious - Comment syntax correct for each file's language
- Validator reports PASSED for all files
Source: gabrielfst30/super-gabriel-claude-toolkit — distributed by TomeVault.