nim-doc-comments

Files (4)

• SKILL.md
• module_docs.md · references/
• proc_and_type_docs.md · references/
• runnable_examples.md · references/

SKILL.md (first lines)

# Nim Doc Comments

## Rules

### Placement

- `##` is a doc comment — `nim doc` picks it up. `#` is a regular comment and is ignored by docs.
- Module docs go at the top of the file, before imports.
- Proc/func/iterator/template/converter docs go immediately after the signature line, before the body.
- Inside `type`, `const`, and `let` blocks, attach docs to the declaration line with trailing `##`.
- Multi-line docs continue with `##` on the following lines, aligned under the declaration.
- Enum value and object field docs go on their declaration lines.
- Do not put a standalone `##` line above a declaration inside a `type` or `const` block and expect it to attach.

### Visibility

- Only exported symbols (`*`) appear in rendered docs. Non-exported symbols are hidden.

### runnableExamples

- Do not add `runnableExamples:` by default.
- If used, place `runnableExamples:` after doc text and before implementation statements.
- `nim doc` compiles and runs all `runnableExamples:` blocks.

### Content

- Start with a short summary sentence. Explain behavior, contracts, and constraints.
- Skip comments that only restate the symbol name or obvious type info.

## Workflow

1. Identify the exported API.
2. Place each doc comment using the correct source layout.
3. Run `nim doc path/to/module.nim`.
4. Check source placement and rendered output.
5. Fix the source comments. Never edit generated output.

## Common Mistakes

| Mistake | Why it's wrong |
|---------|----------------|
| Putting a proc doc comment above the proc signature | `nim doc` treats it as module documentation, not proc documentation. |
| Putting a standalone `##` line above a declaration inside a `type` or `const` block | It does not attach to that symbol; put the doc on the declaration line. |
| Checking only rendered HTML | A misplaced module-style comment can still render, so source placement still needs inspection. |

## References

- `references/module_docs.md` — Line and block forms for module docs and top-level examples.
- `references/proc_and_type_docs.md` — Doc placement for exported declarations and fields.
- `references/runnable_examples.md` — `runnableExamples` forms with placement and compiler flags.

From Vyrnexis/nim-agent-template, MIT.

More from Vyrnexis/nim-agent-template