Llegamos a ustedes gracias a:



Noticias

Mozilla ofrece documentación de proyectos al estilo Python a JavaScript

[21/07/2017] Buscando una herramienta de documentación más completa para grandes proyectos de JavaScript, Mozilla ha presentado Sphinx-js, un complemento que extrae documentación de JavaScript en formato JSDoc hacia la herramienta de documentación Sphinx usada en el mundo de Python.

Sphinx-js consume documentos y etiquetas desde el lenguaje de marcado JSDoc utilizado para documentar bibliotecas y APIs de JavaScript. Sphinx-js delega el análisis al propio JSDoc. Por su parte, la herramienta Sphinx se utiliza para inicializar una carpeta de documentos en la carpeta raíz de su proyecto, con lo cual se activa el complemento y uno documenta su código usando el sistema de análisis y marcado de texto plano reStructuredText.

"Cuando llegue el momento de pedir alguna documentación extraída, uno usa una de las directivas especiales de Sphinx-js, modeladas después de ejemplo maduro de autodoc centrado en Python, afirmó Erik Rose de Mozilla. Documentación se mantiene compatible con las herramientas de JavaScript.

Los desarrolladores pueden agregar ejemplos largos que residan en los archivos reStructuredText y conformar un manual. Sphinx-js también cuenta con una directiva para las clases, ya sea de ECMAScript 2015 o funciones como directores. La herramienta opcionalmente puede iterar sobre los miembros de la clase, documentando en el camino. También se puede controlar el orden. Se soportan las referencias para las entidades JavaScript del mismo nombre las cuales de otra forma colisionarían.

El complemento Sphinx-js se puede descargar de forma gratuita de Python Package Index. Sphinx-js nació de un deseo de tener herramientas para la documentación de JavaScript más allá de los que soporta JSDoc. Rose afirmó que JSDoc ha tenido beneficios como etiquetas bien definidas para describir las estructuras comunes y herramientas como Closure Compiler para colgarse de esas etiquetas. Aun así, el producto es simplemente una lista alfabética de lo que se encuentra en un proyecto. Las funciones están aplanadas, lo cual permite que los nuevos usuarios infieran las relaciones y las ordenen. Esto puede funcionar para pequeñas bibliotecas, pero no funciona para grandes bibliotecas como el marco de trabajo Fathom.