24. Documentation generator

The RST module exposes collection of helper routines to automatically generate Daslang reStructuredText documentation.

All functions and symbols are in “rst” module, use require to get access to it.

require daslib/rst

24.1. Structures

DocGroup

Group of documentation items.

Fields

• name : string - Name of the group.

• func : array<tuple<fn: Function ?;mod: Module ?>> - Functions in the group.

• hidden : bool - Whether the group is hidden.

• _module : Module ? - Module, to which this group belongs.

DocsHook

Hook for RST documentation generation.

Fields

• annotationFilter : lambda<(ann: Annotation ):bool> - Filter for the supported annotations.

• afterEnums : lambda<(f: FILE ?;was_enums:bool):void> - Additional generation hook after the enumerations.

24.2. Document writers

• document_enumerations (doc_file: file; mods: array<Module?>) : bool

• document (name: string; var mod: Module?; fname: string; var groups: array<DocGroup>; hook: DocsHook = DocsHook())

• documents (name: string; mods: array<Module?>; fname: string; var groups: array<DocGroup>; var hook: DocsHook = DocsHook())

• document_enumeration (doc_file: file; mod: Module?; value: auto) : auto

document_enumerations(doc_file: file; mods: array<Module?>) : bool()

Documentation for enumerations in the given modules.

Arguments

• doc_file : file

• mods : array< Module ?>

document(name: string; mod: Module?; fname: string; groups: array<DocGroup>; hook: DocsHook = DocsHook())

Documents the specified module into a RST file.

Arguments

• name : string

• mod : Module ?

• fname : string

• groups : array< DocGroup >

• hook : DocsHook

documents(name: string; mods: array<Module?>; fname: string; groups: array<DocGroup>; hook: DocsHook = DocsHook())

Documents the specified modules into a RST file.

Arguments

• name : string

• mods : array< Module ?>

• fname : string

• groups : array< DocGroup >

• hook : DocsHook

document_enumeration(doc_file: file; mod: Module?; value: auto) : auto()

Documentation for enumeration types.

Arguments

• doc_file : file

• mod : Module ?

• value : auto

24.3. Descriptions

• describe_short (expr: Expression?|smart_ptr<Expression>) : auto

describe_short(expr: Expression?|smart_ptr<Expression>) : auto()

Describes the expression in short form.

Arguments

• expr : option< Expression ?|smart_ptr< Expression >&>

24.4. RST section makers

• make_group (name: string; plus: string = “+”) : string

make_group(name: string; plus: string = "+") : string()

Creates a decorative group header for RST documentation.

Arguments

• name : string

• plus : string

24.5. Group operations

• append_to_group_by_regex (var group: DocGroup; var mod: Module?; var reg: Regex) : DocGroup&

• group_by_regex (name: string; var mod: Module?; var reg: Regex) : DocGroup

• group_by_regex (name: string; var mods: array<Module?>; var reg: Regex) : DocGroup

• hide_group (var group: DocGroup) : DocGroup

append_to_group_by_regex(group: DocGroup; mod: Module?; reg: Regex) : DocGroup&()

Adds functions matching a regex to a documentation group.

Arguments

• group : DocGroup

• mod : Module ?

• reg : Regex

group_by_regex(name: string; mod: Module?; reg: Regex) : DocGroup()

Groups module items by regex.

Arguments

• name : string

• mod : Module ?

• reg : Regex

group_by_regex(name: string; mods: array<Module?>; reg: Regex) : DocGroup()

Groups items in the module by matching their names against the provided regular expression.

Arguments

• name : string

• mods : array< Module ?>

• reg : Regex

hide_group(group: DocGroup) : DocGroup()

Makes the specified documentation group hidden.

Arguments

• group : DocGroup

24.6. Uncategorized

safe_function_name(name: string) : string()

Creates a safe function name by replacing special characters.

Arguments

• name : string

mkdir_rec(path: string) : bool()

Recursively creates directories for the specified path.

Arguments

• path : string

function_label_file(value: smart_ptr<Function>|Function?; drop_args: int = 0) : auto()

Creates a unique label for a function suitable for use in file names.

Arguments

• value : option< FunctionPtr | Function ?>

• drop_args : int

function_label_file(name: auto; value: smart_ptr<TypeDecl>; drop_args: int = 0) : auto()

Creates a unique label for a function based on its name and argument types.

Arguments

• name : auto

• value : smart_ptr< TypeDecl >&

• drop_args : int