JSDoc es un lenguaje de marcado que se utiliza para anotar archivos de código fuente JavaScript . Al usar comentarios que contienen JSDoc, los programadores pueden agregar documentación que describa la interfaz de programación de la aplicación del código que están creando. Luego, esto se procesa, mediante varias herramientas, para producir documentación en formatos accesibles como HTML y formato de texto enriquecido . La especificación JSDoc se publica bajo CC BY-SA 3.0 , mientras que su generador de documentación complementario y biblioteca de analizador es software gratuito bajo la licencia Apache 2.0 .
Versión inicial | 1999 |
---|---|
Último lanzamiento | 3.6.3 (15 de julio de 2019 ) |
Tipo de formato | Formato de documentación de programación |
Contenido por | Archivos de origen JavaScript |
Extendido desde | JavaDoc |
¿ Formato abierto ? | sí |
Sitio web | jsdoc |
Historia
La sintaxis y la semántica de JSDoc son similares a las del esquema Javadoc , que se utiliza para documentar el código escrito en Java. JSDoc se diferencia de Javadoc en que está especializado para manejar el comportamiento dinámico de JavaScript . [1]
Un ejemplo temprano que utiliza una sintaxis similar a Javadoc para documentar JavaScript fue lanzado en 1999 con el proyecto Rhino de Netscape / Mozilla , un sistema de ejecución de JavaScript escrito en Java . Incluía un generador de HTML "JSDoc" de juguete, con una versión hasta 1.3, como ejemplo de sus capacidades de JavaScript. [2]
Todas las generaciones principales de "JSDoc" fueron encabezadas por micmaths (Michael Mathews). Comenzó con JSDoc.pm en 2001, un sistema simple escrito en Perl , en cooperación con el programador canadiense Gabriel Reid. Estaba alojado en SourceForge en un repositorio de CVS . [3] Por JSDoc 1.0 (2007) reescribió el sistema en JavaScript (nuevamente para Rhino), y después de un conjunto de expansiones, JSDoc 2.0 (2008) ganó el nombre "jsdoc-toolkit". Publicado bajo la licencia MIT , fue alojado en un repositorio de Subversion en Google Code . [4] Para 2011, ha refactorizado el sistema en JSDoc 3.0 y ha alojado el resultado en GitHub . Ahora se ejecuta en Node.js . [1]
Etiquetas JSDoc
Algunas de las etiquetas de anotación más populares utilizadas en JSDoc moderno son:
Etiqueta Descripción @author
Nombre del desarrollador @constructor
Marca una función como constructor @deprecated
Marca un método como obsoleto @exception
Sinónimo de @throws
@exports
Identifica un miembro que es exportado por el módulo. @param
Documenta un parámetro de método; se puede agregar un indicador de tipo de datos entre llaves @private
Significa que un miembro es privado @returns
Documenta un valor de retorno @return
Sinónimo de @returns
@see
Documenta una asociación a otro objeto. @todo
Documenta algo que falta / está abierto @this
Especifica el tipo de objeto al que se this
refiere la palabra clave dentro de una función.@throws
Documenta una excepción lanzada por un método @version
Proporciona el número de versión de una biblioteca.
Ejemplo
/ ** @class Círculo que representa un círculo. * / class Circle { / ** * Crea una instancia de Circle. * * @author: moi * @param {número} r El radio deseado del círculo. * / constructor ( r ) { / ** @private * / this . radio = r / ** @private * / this . circunferencia = 2 * Matemáticas . PI * r } / ** * Crea un nuevo círculo a partir de un diámetro. * * @param {número} d El diámetro deseado del círculo. * @return {Circle} El nuevo objeto Circle. * / static fromDiameter ( d ) { return new Circle ( d / 2 ) } / ** * Calcula la circunferencia del círculo. * * @deprecated desde 1.1.0; use getCircumference en su lugar * @return {number} La circunferencia del círculo. * / calculateCircumference () { return 2 * Math . PI * esto . radio } / ** * Devuelve la circunferencia precalculada del círculo. * * @return {número} La circunferencia del círculo. * @since 1.1.0 * / getCircumference () { devuelve esto . circunferencia } / ** * Encuentra una representación de cadena del círculo. * * @override * @return {string} Representación legible por humanos de este Círculo. * / toString () { return `[Un objeto Circle con un radio de $ { this . radio } .] ` } }/ ** * Imprime un círculo. * * @param {Circle} circle * / function printCircle ( circle ) { / ** @this {Circle} * / function bound () { console . log ( this ) } obligado . aplicar ( círculo ) }
Tenga en cuenta que las etiquetas @class
y @constructor
de hecho se pueden omitir: ECMASyntax es suficiente para aclarar sus identidades, y JSDoc hace uso de eso. [5] también @override
se puede deducir automáticamente. [6]
JSDoc en uso
- Closure Linter y Closure Compiler de Google . Este último extrae la información de tipo para optimizar su salida JavaScript.
- TypeScript puede realizar la verificación de tipo para archivos JavaScript con anotaciones de tipo JSDoc. [7] Microsoft ha especificado un nuevo lenguaje TSDoc con etiquetas extensibles.
- El popular editor Sublime Text admite JSDoc a través del complemento DocBlockr o DoxyDoxygen
- La sintaxis JSDoc se ha descrito en detalle en el libro de Apress Foundations of Ajax ISBN 1-59059-582-3 .
- IntelliJ IDEA , NetBeans , Visual Studio Code y RubyMine comprenden la sintaxis JSDoc.
- Aptana Studio, basado en Eclipse, es compatible con ScriptDoc.
- Mozile , el editor en línea de Mozilla usa JSDoc.pm.
- El marco de la aplicación Helma utiliza JSDoc.
- La documentación de SproutCore se generó utilizando JSDoc. [1]
- Visual Studio , WebStorm y muchos otros entornos de desarrollo integrados o editores de texto ofrecen finalización de código y otra asistencia basada en comentarios JSDoc.
- El editor Atom de código abierto es compatible con JSDoc a través del complemento atom-easy-jsdoc .
Ver también
- Comparación de generadores de documentación
- Herramientas de cierre de Google
Referencias
- ^ a b "JSDoc" . GitHub . jsdoc. 4 de septiembre de 2019 . Consultado el 4 de septiembre de 2019 .
- ^ "Ejemplo de Rhino: jsdoc.js" . GitHub . Proyecto Mozilla. 6 de mayo de 1999.
- ^ "JSDoc" . SourceForge . Conversión de Git
- ^ "jsdoc-toolkit" . Código de Google . Conversión de Git
- ^ "Clases ES 2015" . Utilice JSDoc .
- ^ "@override" . Utilice JSDoc .
- ^ "Comprobación de tipos de archivos JavaScript" . Documentación de TypeScript .
enlaces externos
- Sitio web oficial de JSDoc , para tutoriales y documentos sobre el uso
- JSDoc Github oficial , para código actualizado
- "Anotación de JavaScript para el compilador de cierre" , documentación de las herramientas de cierre, sitio web para desarrolladores de Google