Guía de Uso de Templates - AudioLab¶

Cómo Usar Templates para Crear Documentación Consistente

🎯 Casos de Uso¶

Caso 1: Crear Nuevo Sistema Raíz (Carpeta XX_NOMBRE)¶

Cuándo: Estás creando una carpeta raíz nueva (00-20)

Pasos:

Copiar template:

cp _templates/root/README.md.template XX_NEW_SYSTEM/README.md

Reemplazar placeholders:

# Buscar y reemplazar:
[SYSTEM_NUMBER]     → 21
[SYSTEM_NAME]       → NEW_SYSTEM
[BRIEF_TITLE]       → Advanced Audio Processing
[ONE_LINE_DESCRIPTION] → System for advanced DSP algorithms

Crear estructura _docs/:

mkdir -p XX_NEW_SYSTEM/_docs/{reports,audits,analytics,architecture,guides}

Rellenar secciones:
Purpose (qué problema resuelve)
Architecture (subsistemas)
Quick Start (ejemplo mínimo)
Status (versión, estado)

Validar:

.\scripts\validate_structure.ps1 XX_NEW_SYSTEM

Caso 2: Crear Nuevo Subsistema (XX_YY_subsystem)¶

Cuándo: Añades un subsistema a un sistema existente

Pasos:

Copiar template:

cp _templates/subsystem/README.md.template 04_CORE/04_16_new_subsystem/README.md

Reemplazar placeholders:

[SUBSYSTEM_NUMBER]  → 04_16
[SUBSYSTEM_NAME]    → new_subsystem
[ONE_LINE_DESCRIPTION] → Advanced feature for X

Crear estructura:

cd 04_CORE/04_16_new_subsystem
mkdir -p tests examples

Rellenar secciones obligatorias:
Purpose
Architecture (componentes)
Quick Start
API Reference
Testing

Añadir tests:

// tests/test_new_subsystem.cpp
#include <catch2/catch.hpp>

TEST_CASE("Subsystem basic test") {
    REQUIRE(true);
}

Actualizar README del sistema padre:

# En 04_CORE/README.md
├── 04_16_new_subsystem/    # [Descripción breve]

Caso 3: Crear Nuevo Componente (YY_ZZ_component)¶

Cuándo: Añades un componente a un subsistema

Pasos:

Copiar template:

cp _templates/component/README.md.template 04_00_type_system/05_new_types/README.md

Reemplazar placeholders:

[COMPONENT_NAME]       → 05_new_types
[ONE_LINE_DESCRIPTION] → Additional type definitions for X

Completar API:

### Types
\`\`\`cpp
struct MyNewType {
    float value;
};
\`\`\`

Añadir ejemplos:

// Minimal example
MyNewType instance{1.0f};

Actualizar README del subsistema padre

📝 Campos Comunes en Templates¶

Todos los Templates¶

Placeholder	Descripción	Ejemplo
`[ONE_LINE_DESCRIPTION]`	Descripción de 1 línea	"System for real-time audio processing"
`[YYYY-MM-DD]`	Fecha actual	2024-10-16
`[X.Y.Z]`	Número de versión	1.0.0

Template Root¶

Placeholder	Descripción	Ejemplo
`[SYSTEM_NUMBER]`	Número de sistema (00-20)	04
`[SYSTEM_NAME]`	Nombre del sistema	CORE
`[BRIEF_TITLE]`	Título descriptivo	Real-Time Audio Engine
`[SUBSYSTEMS_LIST]`	Lista de subsistemas	"00_type_system, 01_interfaces, ..."

Template Subsystem¶

Placeholder	Descripción	Ejemplo
`[SUBSYSTEM_NUMBER]`	Número (XX_YY)	04_00
`[SUBSYSTEM_NAME]`	Nombre	type_system
`[COMPONENTS_LIST]`	Lista de componentes	"00_fundamental_types, 01_simd_types"

Template Component¶

Placeholder	Descripción	Ejemplo
`[COMPONENT_NAME]`	Nombre del componente	fundamental_types
`[API_DESCRIPTION]`	Descripción de API	"Sample types and constants"

✅ Checklist de Completitud¶

Antes de Commit¶

Todos los [PLACEHOLDERS] reemplazados
Ejemplos de código funcionan (compilan)
Links internos apuntan a archivos existentes
Estructura de directorios creada
Tests básicos añadidos (si hay código)
README del padre actualizado
Validación ejecutada

Para Subsistemas¶

Purpose clara y concisa
Architecture con diagrama/descripción
Quick Start con ejemplo funcional
API Reference completada
Testing section con instrucciones
Al menos 1 test funcional
Dependencies listadas

Para Sistemas Raíz¶

🛠️ Scripts de Ayuda¶

Crear desde Template (Automático)¶

# Crear sistema raíz
.\scripts\create_from_template.ps1 `
    -Type root `
    -Name "21_NEW_SYSTEM" `
    -Title "Advanced Processing" `
    -Description "System for advanced audio algorithms"

# Crear subsistema
.\scripts\create_from_template.ps1 `
    -Type subsystem `
    -Parent "04_CORE" `
    -Number "16" `
    -Name "new_subsystem" `
    -Description "Advanced feature for X"

# Crear componente
.\scripts\create_from_template.ps1 `
    -Type component `
    -Parent "04_00_type_system" `
    -Number "05" `
    -Name "new_types"

Validar Estructura¶

# Validar sistema completo
.\scripts\validate_structure.ps1 04_CORE

# Validar subsistema
.\scripts\validate_structure.ps1 04_CORE/04_00_type_system

# Dry-run (no modifica archivos)
.\scripts\validate_structure.ps1 04_CORE -DryRun

Generar Índice¶

# Generar índice de documentación
.\scripts\generate_index.ps1

# Output: _docs/INDEX.md con todos los links

📊 Ejemplos Reales¶

Ejemplo 1: Sistema Bien Documentado¶

04_CORE es el ejemplo de referencia: - ✅ README completo con todos los campos - ✅ Sistema _docs/ con auditorías - ✅ Architecture documentation - ✅ La mayoría de subsistemas documentados

Ver: 04_CORE/README.md y 04_CORE/_docs/

Ejemplo 2: Subsistema Ejemplar¶

04_00_type_system es el gold standard: - ✅ README detallado con ejemplos - ✅ Todos los componentes documentados - ✅ Tests comprehensivos - ✅ Performance notes

Ver: 04_CORE/04_00_type_system/README.md

Ejemplo 3: Lo Que NO Hacer¶

04_12_error_recovery (antes de mejoras): - ❌ Sin README - ❌ Sin documentación de strategy - ❌ Sin ejemplos - ❌ Tests incompletos

🎓 Tips y Trucos¶

1. Usar Find & Replace¶

En VSCode:

Ctrl+H
Find: \[SYSTEM_NAME\]
Replace: NEW_SYSTEM
Replace All

2. Mantener Ejemplos Simples¶

// ✅ GOOD: Minimal, focused
Sample s = 1.0f;
processample(s);

// ❌ BAD: Too complex for introduction
auto processorChain = ProcessorChainBuilder()
    .addStage<GainStage>(6.0f)
    .addStage<FilterStage>(FilterType::LowPass, 1000.0f)
    .build();

3. Links Relativos¶

// ✅ GOOD: Relative paths
[Type System](../04_00_type_system/README.md)

// ❌ BAD: Absolute paths
[Type System](C:\AudioDev\audio-lab\04_CORE\04_00_type_system\README.md)

4. Actualizar en el Momento¶

# ✅ DO: Document as you code
git add new_feature.cpp new_feature.hpp README.md
git commit -m "Add feature X with documentation"

# ❌ DON'T: Document "later"
git add new_feature.cpp
git commit -m "Add feature X"
# (README never gets updated)

🚨 Errores Comunes¶

Error 1: Dejar Placeholders¶

# ❌ BAD
## Purpose
[Explicar en 2-3 párrafos...]

# ✅ GOOD
## Purpose
This subsystem provides type-safe wrappers for audio samples,
ensuring compile-time validation of sample rates and formats.

Error 2: Ejemplos que No Compilan¶

// ❌ BAD: Code has errors
auto result = nonExistentFunction();

// ✅ GOOD: Actually works
#include "real_header.hpp"
auto result = actualFunction(validParams);

Error 3: Links Rotos¶

// ❌ BAD: File doesn't exist
[See this](../non_existent_file.md)

// ✅ GOOD: Verify file exists
[See this](../04_00_type_system/README.md)

Error 4: Copiar-Pegar Sin Adaptar¶

# ❌ BAD: Copy-paste from other subsystem
This subsystem handles memory management...
# (pero es el subsystem de math primitives!)

# ✅ GOOD: Adapt to actual content
This subsystem provides fast mathematical approximations
for real-time DSP applications.

📚 Referencias¶

💬 Preguntas Frecuentes¶

Q: ¿Debo usar template para TODO código nuevo?¶

A: Sí. Templates garantizan consistencia y completitud.

Q: ¿Puedo modificar el template después de aplicarlo?¶

A: Sí, el template es un punto de partida. Personaliza según necesites.

Q: ¿Qué hago si el template no tiene una sección que necesito?¶

A: Añádela. Los templates son mínimos requeridos, puedes extender.

Q: ¿Debo rellenar TODAS las secciones?¶

A: Sí, o marcar como "N/A" si no aplica con explicación.

Q: ¿Qué pasa si mi componente es muy simple?¶

A: Usa component template (más corto) en vez de subsystem template.

🔄 Feedback y Mejoras¶

Encontraste un problema con el template? 1. Documéntalo 2. Propón mejora 3. Actualiza template 4. Notifica al equipo

Template Version: 1.0.0 Last Updated: 2024-10-16

Use templates, stay consistent! 📝