# Natspec

> Generates NatSpec-style documentation comments for complex implementations in any language or framework. Use when the user wants to add, complete, or audit documentation comments. Works with TypeScript, JavaScript, Solidity, Python, Rust, Go, and any other language. Triggers on phrases like "natspec", "adicionar natspec", "documentar função", "documentar classe", "gerar docs", "comentários natspec", "missing docs", "document this", "add comments", "adicionar comentários", "documentar implementação", "generate natspec", "@notice", "@param", "@return", "@dev".

- Skill: `gabrielfst30/natspec` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add gabrielfst30/natspec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielfst30/natspec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: gabrielfst30 (https://skillmd.com/u/gabrielfst30)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gabrielfst30/natspec

---


# /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