#selfdoc.extractors.zig

#selfdoc.extractors.zig

Zig source extractor for selfdoc -- parses .zig files to extract public declarations, doc comments, and test blocks for documentation pages.

Uses regex-based parsing (no Zig toolchain required). Handles:

• :::ref -- extract module doc, pub declarations with doc comments
• :::prose-desc -- extract module-level //! doc comments only
• :::table-schema -- extract struct fields as a table
• :::code-test -- extract test blocks
• :::table-config -- extract config file contents as tables (JSON/TOML)

#ZigExtractor

Zig language extractor implementing LanguageExtractor protocol.

#name

def name(self) -> str

#detect

def detect(self, dir_path: str) -> bool

#resolve_path

def resolve_path(self, path_arg: str, source_paths: list[str], base_dir: str) -> str | None

#extract

def extract(self, directive_name: str, attrs: dict[str, str], body: list[str], source_paths: list[str], base_dir: str) -> str

#file_extensions

def file_extensions(self) -> list[str]

#public_symbols

def public_symbols(self, file_path: str) -> list[str]

Extract public (pub) symbols from a Zig source file.

Handles pub fn, pub extern fn, pub export fn, pub inline fn, pub const, and pub var. Skips test blocks and private declarations.

#_resolve_zig_path

def _resolve_zig_path(path_arg, source_paths, base_dir)

Resolve a path argument to a Zig source file or directory.

Tries each source_path prefix, then the base_dir directly. Checks for both directories containing .zig files and direct .zig files.

#_resolve_file_path

def _resolve_file_path(file_path, source_paths, base_dir)

Resolve a file path relative to base_dir or source_paths.

#_extract_module_doc

def _extract_module_doc(source)

Extract module-level doc comments (//! lines) from Zig source.

Returns the doc text with //! prefixes stripped.

#_collect_doc_comment_above

def _collect_doc_comment_above(lines, target_line_idx)

Collect contiguous /// doc comment lines immediately above target_line_idx.

Skips blank lines between the comment block and the declaration. Returns the doc comment text with /// prefixes stripped.

#_handle_ref

def _handle_ref(arg, body, source_paths, base_dir, attrs)

Extract module doc and all pub declarations with their doc comments.

arg is a file path (e.g. "src/core/audio.zig") or a directory path.

#_extract_pub_declarations

def _extract_pub_declarations(source)

Extract all pub declarations from Zig source.

Returns a list of dicts with keys: kind, name, signature, doc.

#_extract_fn_signature

def _extract_fn_signature(lines, start_idx)

Extract a function signature from the declaration line.

Returns the signature without the function body (strips trailing { and ;).

#_clean_signature

def _clean_signature(line)

Clean a const/var declaration line for display.

Strips trailing struct/enum/union body openers and semicolons.

#_handle_prose_desc

def _handle_prose_desc(arg, body, source_paths, base_dir, attrs)

Extract only the module-level //! doc comments as prose markdown.

#_handle_table_schema

def _handle_table_schema(arg, body, source_paths, base_dir, attrs)

Extract struct fields as a markdown table.

arg format: [StructName]

#_extract_structs

def _extract_structs(source)

Extract pub struct type declarations from Zig source.

Returns a list of dicts: {name, doc, fields: [{name, type, default, comment}]}.

#_parse_struct_field

def _parse_struct_field(field_line, lines, line_idx)

Parse a single Zig struct field line.

Zig struct fields look like: name: Type = default, // comment name: Type, // comment name: Type = default,

Returns {name, type, default, comment} or None if not a field.

#_format_struct_table

def _format_struct_table(struct_info)

Format a struct's fields as a markdown table.

#_handle_code_test

def _handle_code_test(arg, body, source_paths, base_dir, attrs)

Extract test blocks from Zig source.

arg format: [test_name] If test_name is provided, extracts only that test block. Otherwise, extracts all test blocks.

#_extract_test_block

def _extract_test_block(source, test_name)

Extract a specific test block by name from Zig source.

Matches: test "name" { ... } Uses brace counting to find the block boundaries.

#_extract_all_test_blocks

def _extract_all_test_blocks(source)

Extract all test blocks from Zig source.

Returns list of (name, source) tuples.

#_handle_table_config

def _handle_table_config(arg, body, source_paths, base_dir, attrs)

Extract config file contents as a documented table.

Supports JSON and TOML. Detects format from file extension.