Me encontraba en la necesidad de documentar el código de Tubular para que sea visible todos los atributos y hermosos controles que tenemos. Apenas estaba pensando que quizás solo haría un montón de documentos planos y que Pikachu guiara mi camino de dolor a la salvación. Pero me dije, si AngularJS tiene documentación no tan mal, seguramente algo estan haciendo.
Llegue al documento de AngularJS en Github titulado Writing-AngularJS-Documentation que explican, nada claro, como realizar la documentación por medio. Para realizar la documentación necesitas comenzar con escribir en tu código todo lo que necesitas explicar usando ngDoc que es un sabor extendido de jsDoc. Es lo mismo pero solo con unos campos adicionales especificos para AngularJS.
Ya con tus archivos JS llenos de comentarios relevantes y detalles que casi nadie lee. Es momento que comience lo bueno, pues hay que montar un paquete llamado Dgeni (nota: por favor instala el Dgeni-packages porque Dgeni por si mismo hace nada) y comenzar a escribir un Javascript que debera procesar los comentarios jsDoc.
Dgeni soporta muchas formas de exportar el contenido, y en los paquetes trae soporte para nunjunks que es una especie de template engine, no tan cool, que puedes usar para generar unos lindos HTML con todo. La verdad que al principio configurar dgeni es un poco raro, por eso mejor les dejo el siguiente ejemplo que use para comenzar https://github.com/petebacondarwin/dgeni-angular. El archivo "dgeni-conf.js" es donde sucede gran parte de la magía.
Finalmente ya puedes mover tu monton de archivos HTML con links internos, o como yo que los bote para usar un método de AngularJS acoplado a un controller que hice. El resultado se puede ver ya en línea: Tubular Documentation. Falta terminar de detallar, pero ya tenemos API DOC!
No hay comentarios:
Publicar un comentario