Comentarios mecanografiados
Este artículo trata sobre comentarios de documentos en TypeScript.
La necesidad de los comentarios de Doc
Los comentarios del documento se pueden ver en la mayoría de los lenguajes de programación. Su objetivo principal es generar documentación para el código base dado.
Usamos JavaDoc para generar la documentación en Java, y JSDoc es el generador de documentación API para JavaScript. El TypeScript usa TSDoc para generar su documentación API.
Use TSDoc para generar documentación API en TypeScript
El TSDoc es una especificación que les dice a los programadores cómo comentar en su base de código. Para que las herramientas puedan generar documentación API y crear metadatos para el código base de TypeScript.
El equipo de Microsoft TypeScript mantiene la especificación TSDoc. En JSDoc, necesitamos usar las anotaciones para especificar los tipos explícitamente.
Dado que TypeScript es un lenguaje escrito, no necesitamos usar anotaciones en TSDoc, y ayuda a generar más documentación informativa sin problemas.
Los comentarios TSDoc comienzan con dos asteriscos, como se muestra a continuación.
/**
*
*
*/
Además, proporciona una marca de anotación @ para especificar información especial como parámetros, tipos de devolución y mucho más, como se muestra a continuación.
export class Square {
/**
* @Returns the area of the given square.
*
* @param width - width of the square
* @param height - the height of the square
* @returns The multiplication of `width` and `height`.
*/
static calculateArea(width: number, height: number): number {
return width * height;
}
}
Use Visual Studio Code para generar documentación de API
El comentario del documento comenzó con dos asteriscos y continúa. Las anotaciones @Returns, @param han proporcionado información adicional sobre el código base.
Podemos usar Visual Studio Code para ver la documentación API generada para la función calculateArea.
Use TypeDoc para convertir comentarios TSDoc a documentación HTML
Los comentarios TSDoc también se pueden utilizar para generar documentación HTML. Luego, debemos usar la herramienta de utilidad TypeDoc para convertir los comentarios TSDoc en documentación HTML procesada.
Primero, es obligatorio instalar typedoc, como se muestra a continuación.
npm install --save-dev typedoc
Entonces podemos generar fácilmente la documentación HTML utilizando la utilidad de línea de comandos typedoc.
typedoc --out docs .
Diferentes herramientas pueden usar comentarios TSDoc en su código TypeScript y analizarlos para generar documentación API, documentación HTML y otra información útil sobre el código base.
Nimesha is a Full-stack Software Engineer for more than five years, he loves technology, as technology has the power to solve our many problems within just a minute. He have been contributing to various projects over the last 5+ years and working with almost all the so-called 03 tiers(DB, M-Tier, and Client). Recently, he has started working with DevOps technologies such as Azure administration, Kubernetes, Terraform automation, and Bash scripting as well.