natspec

name	natspec
description	> Use when this capability is needed.

/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 @notice and @param/@returns
• Private functions have @dev when 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.