egutierrez
7eb7b3d0c8
Snapshot de WIP acumulado de sesiones previas antes de merge wave 1 del flow 0008 (kanban_cpp + agent_runner_api + DoD schema). Incluye: - dev/flows/0008-kanban-cpp-and-agent-workflows.md - dev/issues/0112-0119*.md (7 sub-issues) - WIP previo en cmd/fn/doctor.go, registry/*, modules/, cpp/, etc. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
132 lines
4.2 KiB
Markdown
132 lines
4.2 KiB
Markdown
---
|
|
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.
|