Automatizando la Documentación de un DSL: De 1 Mes a 4 Días
El Problema
Estaba traduciendo los comandos del DSL de Concepto del español al inglés. A mano.
Después de traducir los primeros comandos, me golpeó la realidad: más de 100 comandos que traducir, cada uno con documentación, definiciones de autocompletado y reglas de validación. Al ritmo que llevaba, esto tomaría un mes completo de trabajo tedioso y propenso a errores.
Tenía que haber una mejor manera.
El Insight
Titanium es un framework de JavaScript. Todas sus APIs están documentadas en inglés. Yo estaba recreando documentación que ya existía.
Si podía conectarme al propio formato de documentación de Titanium, podía automatizar todo el proceso.
El archivo: api.jsca - La especificación completa de la API de Appcelerator. Un archivo JSON de 36MB en la raíz de cada SDK de Titanium. Este archivo alimenta el autocompletado en su IDE oficial.
Appcelerator incluso anima a los desarrolladores a usarlo. Perfecto.
El Desafío
Problema 1: Tamaño
36MB de datos JSON. Parsear esto en tiempo real mataría el rendimiento. Necesitaba un formato más liviano.
Problema 2: Estructura
La estructura de la API de Titanium no calzaba con los patrones del DSL de Concepto. Necesitaba mapear entre dos paradigmas distintos:
- Titanium piensa en objetos y métodos
- Concepto piensa en nodos visuales y atributos
Problema 3: Completitud
El archivo de la API tenía todo — pero también le faltaban piezas. Eventos, condicionales y patrones de scripting no estaban en api.jsca. Tendría que agregarlos por separado.
Encontrando la Solución
Encontré a un usuario de GitHub llamado yomybaby que ya había resuelto el problema del parseo. Había construido el autocompletado de Titanium para Atom.io usando una versión condensada de api.jsca.
Su enfoque:
- Parsear el archivo de 36MB una vez
- Extraer solo lo necesario para el autocompletado
- Generar un archivo
ti-completions.jsonde 1MB
Perfecto. Podía adaptar esto a ColdFusion (el lenguaje nativo de Concepto) y usarlo para autogenerar los comandos del DSL.
Parser y Generador de API
Crear manualmente los comandos DSL para más de 100 APIs de Titanium tomaría un mes.
Construí un parser que lee el api.jsca de Titanium y autogenera las definiciones de comandos del DSL de Concepto.
Reduje el archivo de API de 36MB a 1MB, y luego autogeneré 380 páginas de documentación en 4 días en vez de 1 mes.
La Arquitectura
Creé un método llamado ac_ti() que hace de puente entre la estructura de la API de Titanium y el formato DSL de Concepto:
Qué hace:
- Lee el archivo de API condensado (1MB en vez de 36MB)
- Empareja los objetos de Titanium con los patrones de comandos de Concepto
- Genera comandos duplicados para cada variación de la API
- Mapea los valores de atributos al sistema de nodos de Concepto
- Exporta documentación y definiciones de autocompletado
Ejemplo:
Para cada vista de Titanium (Label, Button, ImageView, etc.), ac_ti() crea:
- Un comando de Concepto con la sintaxis correcta
- Documentación con todas las propiedades, eventos y métodos
- Sugerencias de autocompletado con chequeo de tipos
- Alias de valores (ej.
*→Ti.UI.FILL,-→Ti.UI.SIZE) - Handlers de actualización de código en tiempo real para el Modo en Vivo
Antes: Definición manual del comando en español con descripciones y atributos hardcodeados
Después: Vista autogenerada usando ac_ti() - obtiene la documentación directamente de las especificaciones de la API de Titanium
Características clave:
- Auto-actualizado: ¿Nueva versión del SDK? Re-ejecuta el parser. Listo.
- Manejo de obsoletos: Marca automáticamente los métodos deprecados
- Consistente: Cada comando sigue el mismo patrón
- Documentado: Manual de 380 páginas generado automáticamente
Resultados
Antes:
- Más de 100 comandos que traducir a mano
- 1 mes de tiempo estimado
- Propenso a errores e inconsistencias
- Actualizaciones manuales por cada versión del SDK
Después:
- Todos los comandos autogenerados en 4 días
- 380 páginas de documentación (vs. ~100 antes)
- Actualizaciones automáticas del SDK
- Estructura consistente en todos los comandos
- Soporte de autocompletado para toda la API de Titanium
Lo que quedaba pendiente:
El DSL en inglés todavía no estaba listo para producción. Aún necesitaba agregar:
- Handlers de eventos (onClick, onChange, etc.)
- Condicionales (lógica if/else)
- Control de flujo (loops, switches)
- Comandos de scripting (no presentes en api.jsca)
Pero la base era sólida. La parte tediosa estaba automatizada.
Demo temprana del parser de DSL en inglés en acción
Lo Que Aprendí
Sobre automatización:
Cuando te encuentres haciendo trabajo repetitivo, detente. Busca el patrón. ¿Se puede automatizar? En este caso, 4 días de trabajo de automatización me ahorraron 26 días de trabajo manual — y volvieron el sistema más mantenible.
Sobre apoyarse en herramientas existentes:
No inventé la estrategia de parseo. Encontré la solución de yomybaby y la adapté. Los buenos desarrolladores no reinventan la rueda — encuentran las ruedas correctas y las conectan a sus propios sistemas.
Sobre el diseño de DSLs:
Un DSL bien diseñado no debería solo parsear código — debería autodocumentarse. El enfoque de ac_ti() significaba que cada comando generaba automáticamente su propia documentación, autocompletado y reglas de validación.
Sobre perfección vs. progreso:
El DSL en inglés no estaba completo después de 4 días. Faltaban eventos y condicionales. Pero tenía el núcleo funcionando. Lanza la base, itera en los detalles.
El Panorama Mayor
Esto fue parte de construir Concepto DSL, un entorno de programación visual que compilaba diagramas tipo mapa mental en apps móviles Titanium funcionales.
El desafío: la API de Titanium es enorme y evoluciona constantemente. La documentación manual era insostenible.
La solución: Automatizar todo lo que se pueda automatizar. Usar la propia documentación del framework como fuente de verdad.
Este enfoque más tarde se convirtió en la plantilla de cómo Concepto manejaba todas sus extensiones de DSL — no solo Titanium, sino también Vue.js, React y backends Node.js.
La lección: No pelees con tus dependencias. Adóptalas. Si Titanium documenta su API en api.jsca, usa api.jsca. Si la actualizan, tu sistema se actualiza también.
Usa Este Enfoque
Si estás construyendo un DSL o generador de código:
- Encuentra la especificación: La mayoría de los frameworks tienen specs de API legibles por máquina (JSON, XML, definiciones de TypeScript)
- Parsea una vez, genera muchas: Convierte la spec a tu formato interno una sola vez
- Automatiza la documentación: Si tu código es autogenerado, tus docs también deberían serlo
- Maneja la obsolescencia: Las buenas specs marcan las funcionalidades deprecadas — usa esa información
- Versiona apropiadamente: Ata tu generador a versiones específicas del framework
Herramientas que inspiraron esto:
- Docs de la API de Titanium↗ - La fuente de verdad
- Atom Titanium de yomybaby↗ - La inspiración del parseo
- Spec api.jsca↗ - El formato en sí
Herramientas relacionadas:
Si estás construyendo generadores de código, revisa:
- Los archivos
.d.tsde TypeScript para definiciones de tipos - Specs OpenAPI/Swagger para APIs REST
- Esquemas GraphQL para APIs GraphQL
- JSON Schema para validación de datos
Todas estas pueden alimentar la generación automática de código y documentación.