# essim documentation

Auto-generated API reference and high-level design notes for the
[essim](../README.md) system digital twin.

## Layout

- [`user/`](user/) — **user-facing** docs (hand-written intro/tutorial
  + auto-generated command reference). Start at [`user/index.md`](user/index.md).
- [`api/`](api/) — **developer-facing** API reference (Doxygen XML →
  custom Markdown emitter). Browse classes and files directly in
  gitea's Markdown renderer. Top page: [`api/index.md`](api/index.md).
- [`../DESIGN.md`](../DESIGN.md) — implementation notes: domain
  conventions, TUI flow, gotchas. Hand-maintained.
- [`classes.puml`](classes.puml) — PlantUML class diagram for the
  domain model. Render with `plantuml classes.puml` for a PNG/SVG.
- [`Doxyfile.in`](Doxyfile.in) / [`gen_api_md.py`](gen_api_md.py) —
  the toolchain (templated Doxygen config + custom XML→Markdown emitter).

## Regenerating the API reference

The Markdown tree under `doc/api/` is committed so it's readable directly
on gitea. After substantive code changes, regenerate it:

```sh
# 1. Tooling (once): Doxygen, plus a Python 3 interpreter (already on Arch).
pacman -S doxygen

# 2. Configure once (or after editing doc/Doxyfile.in):
cmake -S . -B build

# 3. Regenerate:
cmake --build build --target doc

# 4. Review and commit the updated doc/api/ tree:
git add doc/api/
git status doc/api/
```

Pipeline:

```
src/**/*.{hpp,cpp}  ──┐
README.md            ─┼─► doxygen ─► build/doc/xml/  ─► gen_api_md.py ─► doc/api/
DESIGN.md            ─┘            (Doxyfile.in)

(built essim) ────────► essim --commands-md ──────────────────────────► doc/user/commands.md
```

`doc/user/index.md` and `doc/user/scripting.md` are hand-written; only
`doc/user/commands.md` is regenerated. The `doc` target depends on the
`essim` binary so a stale build is rebuilt before the dump is taken.

If either Doxygen or Python 3 is missing at CMake-configure time the
`doc` target is silently disabled (the regular build still works) and a
status line is emitted in the CMake log telling you which one to install.

## Why a custom emitter rather than `doxybook2` / `moxygen`

- **`doxybook2`** is not packaged in Arch / AUR and gets stale upstream.
- **`moxygen`** drags Node into a pure-C++ project.
- The emitter is one Python file (`gen_api_md.py`, ~330 lines) with
  zero external dependencies — easy to read, easy to tweak, robust to
  Doxygen version changes (the XML schema is stable).

Tailor the output by editing `gen_api_md.py` directly: add columns to
the class table, change the source-link format, group sections
differently, etc.

## Comment style

The codebase uses standard Doxygen markers:

- `///` for single-line briefs.
- `/** … */` for multi-line blocks.
- `@param`, `@return`, `@brief` (or `@short`) tags inside blocks.
- `@throws` for exceptions a function may raise.

`JAVADOC_AUTOBRIEF = YES` is set so the first sentence of a multi-line
comment counts as the brief description without needing an explicit
`@brief` tag.