Document exported Nim modules and APIs with doc comments that `nim doc` actually picks up, including module docs, proc and type docs, field docs, and runnable examples. Use when writing documentation for a Nim library or fixing docs that are missing, attached to the wrong symbol, or rendering incorrectly.
Document exported Nim modules and APIs with doc comments that `nim doc` actually picks up, including module docs, proc and type docs, field docs, and runnable examples. Use when writing documentation for a Nim library or fixing docs that are missing, attached to the wrong symbol, or rendering incorrectly.
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
Identify the exported API.
Place each doc comment using the correct source layout.
Run nim doc path/to/module.nim.
Check source placement and rendered output.
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.
