# LIMAN

## Overview

Documentation system for _Lilush_. LIMAN parses doc comments from Lua
source files and can generate a Wiki-DB MNEME database or a `docs.lua`
file for web serving. Documentation is browsable and searchable through
the shell's wiki mode.

LIMAN is distributed as a LILPACK (`liman`) with a CLI tool and
reusable Lua modules.

## Doc Comment Format

### Module-level documentation

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

```lua
-- 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.

```lua
---! 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:

| Class   | Meaning        |
|---------|----------------|
| `.str`  | string         |
| `.num`  | number         |
| `.bool` | boolean        |
| `.tbl`  | table          |
| `.func` | function       |
| `.file` | file path      |
| `.dir`  | directory path |
| `.nil`    | nil            |
| `.opt`    | optional argument (can be omitted) |
| `.or_nil` | return value that may be nil |
| `.err`    | error return value |

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}
```

## Wiki-DB Database

Documentation is stored as a Wiki-DB conforming MNEME database
(`liman.mneme`) under the wiki directory. The database is self-describing
and viewable through the shell's wiki mode (F3).

### 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
```

## LILPACK Modules

The `liman` LILPACK provides the following modules and CLI tool:

| Module | Role |
|--------|------|
| `liman` | Doc comment parser (extraction functions) |
| `liman.scanner` | File discovery and batch scanning using `std.fs` |
| `liman.wiki` | Wiki-DB MNEME database generator |
| `liman.export` | `docs.lua` exporter with RELIW handler |
| `cli/liman` | CLI entry point (`liman wiki`, `liman export`) |