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

# 0107f — Docs API publica de modulos

Parte del issue principal [0107](0107-modules-standardization.md).

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

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

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