fn_registry/dev/issues/completed/0107f-modules-api-docs.md

id, title, status, type, domain, scope, priority, depends, blocks, related, created, updated, tags

id	title	status	type	domain	scope	priority	depends	blocks	related	created	updated	tags
0107f	modules/README.md (catalogo) + docs/MODULES_API.md (contrato publico por modulo)	pendiente	docs	meta cpp-stack docs	registry	alta			0107	2026-05-17	2026-05-17	modules docs api contract

0107f — Docs API publica de modulos

Parte del issue principal 0107.

Objetivo

Resolver "no hay un sitio canonico que diga como usar un modulo". Dos archivos:

1. modules/README.md — catalogo (tabla con nombre, version, descripcion 1-linea, link a contrato).
2. docs/MODULES_API.md — contrato canonico publico de cada modulo (template + ejemplos).

Estructura modules/README.md

# Modulos C++ del registry

Bundles versionados de funciones del registry expuestos como static libs.
Apps opt-in via `app.md::uses_modules` + `target_link_libraries(... fn_module_<X>)`.

| Modulo | Version | Static lib | Header | Entry | Descripcion | Contrato |
|---|---|---|---|---|---|---|
| framework_cpp | 1.1.0 | fn_framework | cpp/framework/app_base.h | fn::run_app(cfg, render) | Shell ImGui (GLFW+OpenGL+ImGui+ImPlot+themas+layouts+logger) | [framework_cpp](../docs/MODULES_API.md#framework_cpp) |
| data_table_cpp | 2.0.0 | fn_module_data_table | modules/data_table/data_table.h | data_table::render(...) | Tabla completa TQL+viz+drill+AI+button events | [data_table_cpp](../docs/MODULES_API.md#data_table_cpp) |

## Como anadir un modulo

Ver [docs/MODULES_API.md#cycle](../docs/MODULES_API.md#ciclo-de-vida-de-un-modulo) y `.claude/rules/cpp_apps.md`.

Estructura docs/MODULES_API.md

# Modules API

Contrato publico canonico de cada modulo C++ del registry. Una app DEBE
poder integrar un modulo leyendo solo esta pagina (sin abrir el .cpp).

## Template por modulo

### <module_name>

**Static lib target:** `<cmake_target>`
**Header path:** `<include>`
**Namespace:** `<namespace>`
**Entry function:** `<signature>`
**State struct:** `<type>` (lifecycle: <lifecycle notes>)
**Public types:** lista de tipos publicos consumidos (TableInput, TableEvent, etc.)
**Dependencias transitivas:** lista de libs externas (lua54, imgui, etc.)
**Min ImGui version:** <X.Y>
**Thread safety:** <main thread only | safe to call from any thread>

#### Opt-in en una app

1. `app.md`: anadir `uses_modules: [{name: <id>, min_version: "X.Y"}]`.
2. `CMakeLists.txt`: `target_link_libraries(<app> PRIVATE <cmake_target>)`.
3. Header: `#include "<header_path>"`.
4. Reservar `<state>` persistente entre frames.
5. Llamar `<entry>` cada frame.

#### Ejemplo minimo

```cpp
[bloque de codigo lanzable]

Eventos / callbacks

[Tabla de eventos publicos si aplica]

Gotchas

[Lista de gotchas conocidos]

Version policy

Semver. Major = breaking ABI/API de la entry function o State publico. Minor = additive (nuevo evento, nuevo renderer opcional). Patch = bugfix.

---

framework_cpp

[Aplicar template]

data_table_cpp

[Aplicar template]

Ciclo de vida de un modulo

1. Crear modules/<name>/ con module.md, CMakeLists.txt, <name>.cpp, <name>.h.
2. module.md::members lista funciones del registry que el modulo bundla.
3. module.md::version SemVer estricto.
4. CMakeLists.txt define static lib fn_module_<name> con sus deps.
5. Anadir entrada en modules/README.md.
6. Anadir seccion en docs/MODULES_API.md siguiendo el template.
7. fn index registra el modulo.
8. Cada bump de version: /version modules/<name> <major|minor|patch> "<reason>" (ver .claude/commands/version.md).

## Tareas

- [ ] **6.1** Crear `modules/README.md` con tabla canonica.
- [ ] **6.2** Crear `docs/MODULES_API.md` con template + secciones para los 2 modulos actuales.
- [ ] **6.3** Anadir referencia desde `.claude/rules/cpp_apps.md` a `docs/MODULES_API.md`.
- [ ] **6.4** Anadir referencia desde `cpp/PATTERNS.md` a `docs/MODULES_API.md`.
- [ ] **6.5** Anadir referencia desde `.claude/CLAUDE.md` en la seccion "Estructura" listando `modules/` y enlazando docs.

## Riesgos

- Doc drift: facil que `module.md` y `MODULES_API.md` se desincronicen. Mitigacion: `fn doctor modules` (0107a) verifica que cada modulo registrado tiene seccion en `MODULES_API.md`. Si no, warning.