nixdoc

A spec-based parser for Nixdoc documentation comments (RFC145).

Nixdoc uses /** … */ doc comments containing Markdown with structured sections introduced by level-1 headings (# Section). This crate parses that format into a typed [DocComment] structure, extracting the description, type signature, arguments, examples, and any other sections.

Quick start

use nixdoc::DocComment;

// Simple one-liner:
let doc = DocComment::parse("/** Returns the identity value. */").unwrap();
assert_eq!(doc.title(), Some("Returns the identity value."));
assert!(doc.sections.is_empty());

use nixdoc::DocComment;

// Multi-section comment (without inner code fences for this example):
let doc = DocComment::parse(
    "/**\n  Adds two numbers.\n\n  # Arguments\n\n  - [a] First\n  - [b] Second\n*/"
).unwrap();

assert_eq!(doc.title(), Some("Adds two numbers."));
let args = doc.arguments();
assert_eq!(args.len(), 2);
assert_eq!(args[0].name, "a");
assert_eq!(args[1].name, "b");

Comment format

A Nixdoc comment starts with /** and ends with */. Content is indented (typically by two spaces) and the indentation is automatically stripped. Sections are introduced by level-1 Markdown headings (# Section). The section body is Markdown text and may contain fenced code blocks.

Recognised section headings (case-insensitive): Type, Arguments/Args, Example, Examples, Note, Notes, Warning/Warnings/Caution, Deprecated.