lilpacks/liman

Module-level documentation

Placed at the top of a source file, after the SPDX license header. Uses a level-2 long comment (--[==[...]==]):

-- SPDX-License-Identifier: ...
-- Copyright ...
--[==[
File system operations for reading, writing, and manipulating
files and directories.
]==]

local core = require("std.core")

Only the first --[==[...]==] block in the file is treated as the module description. It must appear before any local or require statements (blank lines and single-line comments between the license header and the doc block are fine).

Function-level documentation

Uses ---! (short description), ---@ (signature), and optionally --[===[...]===] (detailed description). Must immediately precede a function definition.

---! Read the entire contents of a file
---@ read_file(`path`{.str}) -> `content`{.str .or_nil}, `err`{.str .err}
--[===[
Reads the file at the given path and returns its contents as a string.
Returns nil and an error message if the file cannot be read.
]===]
local read_file = function(path)
    -- ...
end

Rules:

• ---! — required, single line, short description

• ---@ — required, single line, function signature with type annotations

• --[===[...]===] — optional, multi-line detailed description (markdown)

• The doc block must be followed by a function definition (local NAME = function, local function NAME, or NAME = function for forward-declared/recursive functions). A bare local NAME forward declaration between the doc block and NAME = function is allowed.

• The function name in ---@ is the source of truth for the documented name (supports method syntax like obj:method(...))

• Orphaned doc blocks (not followed by a function def) produce a warning but don't fail the generation

• Blank lines between ---!, ---@, and --[===[ are not allowed; the three markers must be consecutive

Type classes

Reuse the existing argparser type classes for signature annotations:

These appear inside backtick-brace pairs in signatures: `path`{.str}

A variable can have multiple classes: `opts`{.tbl .opt}

Argument conventions

Arguments without .opt are required (this is the default). There is no .req class. Use .opt only for arguments that can be omitted:

`mode`{.str .opt}

Return value conventions

Use .or_nil for return values that may be nil in some code paths. Use .err for error return values. Combine with the actual type class:

`content`{.str .or_nil}, `err`{.str .err}

Example signature:

read_file(`path`{.str}) -> `content`{.str .or_nil}, `err`{.str .err}

Database structure

__wiki manifest — declares the database as a Wiki-DB:

• version: 1

• title: "Lilush API Reference"

• content_keyspace: "content" (FT-indexed)

• content_format: "markdown"

• meta_keyspace: "meta"

• indexes: single alphabetical browsing index (by_alpha)

• entry_point: browse mode on by_alpha

content FT keyspace — one entry per module and per function:

• Module keys: std.fs, std.tbl, etc. Content includes module description, submodule list, and a function summary table.

• Function keys: std.fs.read_file, etc. Content includes summary, signature, and optional detailed description.

meta KV keyspace — per-entry JSON metadata:

• Module: {"title": "std.fs", "type": "module"}

• Function: {"title": "std.fs.read_file", "type": "function", "module": "std.fs"}

by_alpha sorted set — alphabetical browsing index over all entries.

Generating the database

Use the liman CLI (installed via the liman LILPACK):

liman wiki [-o output_path] [-t title] <source_dirs...>

Default output path: ~/.local/share/lilush/wiki/liman.mneme

Example — generate docs for the core lilush modules:

liman wiki src/std src/crypto src/shell src/term src/dns src/lev

Generating docs.lua for web serving

liman export [-o output_path] <source_dirs...>

Produces a self-contained docs.lua with serialized documentation and an embedded RELIW request handler for serving rendered HTML.

Browsing documentation

Open wiki mode with F3, then:

wiki liman                     Open the API reference database
browse                         List all entries alphabetically
view std.fs                    Module description + function table
view std.fs.read_file          Full function documentation
search read_file               Full-text search across all entries
info                           Show database metadata