This document describes the automated documentation generation system in Basalt2, which extracts structured comments from Lua source files and converts them into markdown reference documentation. The system consists of two main components: the BasaltDoc module for parsing and generating documentation, and generate-docs.lua for orchestrating the generation process across the file system.
For information about the broader build system that invokes these tools, see page 7.1. For type definition generation for IDE support, see page 7.4. For the configuration metadata extraction system, see page 7.2.
The documentation system extracts specially-formatted comments from source files and generates structured markdown documentation. This process is fully automated through the GitHub Actions pipeline and supports both ComputerCraft and standard Lua environments.
Sources: tools/generate-docs.lua1-163
Documentation is embedded in source files using special LuaDoc-style comments. The parser recognizes two comment types:
---): LuaDoc annotations with type information--): Descriptive text| Annotation | Purpose | Example |
|---|---|---|
@class | Define a class and its inheritance | ---@class Tree : VisualElement |
@property | Document a property with type and default | ---@property nodes table {} The tree structure |
@param | Document function parameter | ---@param node table The node to expand |
@return | Document return value | ---@return Tree self The Tree instance |
@function | Mark as a function (inferred from code) | function Tree:expandNode(node) |
@shortDescription | Brief one-line description | ---@shortDescription Expands a node |
@usage | Code example | ---@usage tree:expandNode(rootNode) |
@event | Document an event | ---@event node_select {node} Fired when selected |
@field | Document a field | ---@field terminal table The terminal object |
@combinedProperty | Property that combines multiple properties | ---@combinedProperty size {width, height} |
@private | Mark next function as private (exclude from docs) | ---@private |
@protected | Mark function as overridable | ---@protected |
@splitClass | Output class to separate file | ---@splitClass |
@title | Section title | ---@title Core Functions |
Sources: tools/markdown.lua5-23
Sources: src/elements/Tree.lua4-69
The BasaltDoc module provides parsing and generation capabilities. It processes source files line-by-line, maintaining state across comment blocks to build an abstract syntax tree representation of the documentation.
Sources: tools/generate-docs.lua131
The BasaltDoc.generateMarkdown(ast) function transforms the parsed AST into formatted markdown documentation. It processes classes and their members to generate structured output.
Each class generates a markdown document with the following sections in order:
Property tables are generated from @property annotations:
Generated from source annotations:
Sources: src/elements/Tree.lua13-27
Function blocks include signature, description, parameters, returns, and usage:
Generated from annotations: ```lua --- Expands a node --- @shortDescription Expands a node to show its children --- @param node table The node to expand --- @return Tree self The Tree instance function Tree:expandNode(node) Sources: src/elements/Tree.lua61-69
The generate-docs.lua script orchestrates the entire documentation generation process. It provides a file system abstraction layer for cross-platform compatibility between ComputerCraft and standard Lua environments.
The script detects the runtime environment and provides a unified fileSystem interface:
For standard Lua, file system operations use shell commands via io.popen:
| Function | Shell Command | Purpose |
|---|---|---|
pathExists(path) | [ -e 'path' ] | Check if path exists |
isDirectory(path) | [ -d 'path' ] | Check if path is directory |
makeDirectory(path) | mkdir -p 'path' | Create directory recursively |
listDirectory(dir) | ls -1 'dir' | List directory contents |
Sources: tools/generate-docs.lua9-86
The main generation loop processes all Lua files in the source directory:
Sources: tools/generate-docs.lua88-163
| Symbol | Type | Purpose | Location |
|---|---|---|---|
arg | Variable | Command-line arguments | tools/generate-docs.lua1 |
SRC_DIR | Variable | Source directory path (default: "src") | tools/generate-docs.lua2 |
OUT_DIR | Variable | Output directory path (default: "build_docs/docs/references") | tools/generate-docs.lua3 |
BasaltDoc | Module | Documentation parsing and generation | tools/generate-docs.lua7 |
fileSystem | Table | Unified file system API | tools/generate-docs.lua9-86 |
getLuaFiles(dir) | Function | Recursively find all .lua files | tools/generate-docs.lua94-114 |
The recursive file scanner:
Sources: tools/generate-docs.lua1-114
The generator mirrors the source directory structure in the output:
src/ ├── elements/ │ ├── Tree.lua → build_docs/docs/references/elements/Tree.md │ └── Button.lua → build_docs/docs/references/elements/Button.md ├── plugins/ │ └── animation.lua → build_docs/docs/references/plugins/animation.md └── main.lua → build_docs/docs/references/main.md The path transformation logic:
Sources: tools/generate-docs.lua128-129
The @splitClass annotation allows a single source file to generate multiple output files, useful for plugin files that extend multiple classes. When processing a file with split classes, the generator creates separate markdown files for each class extension.
For example, a plugin file that adds methods to both BaseElement and Container can use:
This generates separate documentation files:
pluginname_BaseElement.md for BaseElement extensionspluginname_Container.md for Container extensionsSources: Referenced in annotation system documentation
The documentation generator includes several validation mechanisms:
The generator validates content at multiple stages:
The generator handles markdown output as either string or table:
Sources: tools/generate-docs.lua124-150
File operations include error checking with informative messages:
Sources: tools/generate-docs.lua119-160
The documentation generator is invoked by the GitHub Actions workflow during the build process. It runs as part of the automated build pipeline alongside configuration generation, type definition generation, and bundling.
The workflow invokes the generator with explicit directory arguments:
The generated documentation is:
build_docs/docs/references/Sources: Referenced in build system architecture, tools/generate-docs.lua2-3
The script accepts two optional arguments:
| Argument | Default | Purpose |
|---|---|---|
arg[1] | "src" | Source directory to scan for .lua files |
arg[2] | "build_docs/docs/references" | Output directory for generated markdown |
Sources: tools/generate-docs.lua1-3
The generator maintains the source directory structure in the output:
src/elements/Tree.lua → build_docs/docs/references/elements/Tree.md src/elements/Button.lua → build_docs/docs/references/elements/Button.md src/plugins/animation.lua → build_docs/docs/references/plugins/animation.md src/main.lua → build_docs/docs/references/main.md Path transformation logic:
Sources: tools/generate-docs.lua128-129
From property annotations in src/elements/Tree.lua13-31 the generator produces:
From function annotations in src/elements/Tree.lua61-69 the generator produces:
From event definitions in src/elements/Tree.lua33-34:
Sources: src/elements/Tree.lua13-34
The documentation system provides automated extraction and generation of API documentation from annotated source files. Key components include:
@class, @property, @param, @return, etc.The system ensures documentation stays synchronized with code by extracting it directly from source files during the build process.
Sources: tools/generate-docs.lua1-163 tools/markdown.lua1-533
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.