Agregar metadatos a su documentación
Proporcionar una buena documentación es una tarea esencial para todo desarrollador. No solo ayuda a sus compañeros a comprender rápidamente su razonamiento y tal vez su proceso de pensamiento, sino que también lo ayuda a ingresar al código más rápido en caso de que regrese después de un par de meses.
Por lo tanto, pensé en crear una lista (incompleta) de etiquetas especiales para usar con los comentarios de JSDoc. Esos son los que personalmente uso con más frecuencia y que han demostrado proporcionar un beneficio real.
Un entrante básico
El siguiente ejemplo de código muestra un ejemplo simple y básico que debe usarse para cada documentación. Anota el propósito, los parámetros y el tipo de retorno.
/**
* Get a sum all terms provided.
*
* @param {...number} terms Array of terms to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Código de ejemplo en la documentación.
Puede proporcionar un ejemplo de código en línea real con la etiqueta "@example" para aclarar ciertos casos de uso. Esta etiqueta también se puede usar para mostrar rápidamente posibles casos extremos en un escenario del mundo real.
/**
* Get a sum all terms provided.
*
* @example
* ```ts
* import { sum } from "./source";
* const result = sum(40, 2);
* ```
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Miembro de qué módulo
Utilice la etiqueta "@memberOf" para definir qué módulo o variable principal alberga el código documentado.
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Anotación de enlace
Puede usar la etiqueta "@see" junto con la etiqueta "@link" para proporcionar una documentación de URL con el formato correcto, en lugar de pegar algunas URL en línea de la documentación principal.
/**
* @see (@link module:source.sum}
* @see (@link https://www.some-source.com}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Documentación de tipo genérico
Si su código usa tipos genéricos, puede usar la etiqueta "@template" para definir el nombre del tipo genérico. Este nombre se usa luego en las etiquetas comunes "@param" como referencia de tipo.
/**
* @template T
* @param {...T} Array of numbers to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Definición del autor de un fragmento de código
En ciertos casos, es importante anotar también al autor. Esto se puede lograr simplemente con la etiqueta "@author". No solo puede proporcionar su nombre, sino también un correo electrónico como referencia de contacto.
/**
* @author Tom Schönmann <[email protected]>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Código obsoleto
No hay mucho que contar sobre la etiqueta "@deprecated", ya que hace exactamente lo que esperas. Esta etiqueta se usa comúnmente en las API y también puede hacer referencia al nuevo código.
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Versión
Use la etiqueta "@version" para documentar una versión para el código dado. Tenga en cuenta que esta etiqueta no hace referencia a la versión de la aplicación, sino a la propia. Un incremento de esta versión significa que este código específico ha cambiado.
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Desde cuando el código está disponible para usar
Puede usar la etiqueta "@since" para documentar desde qué número de versión se agregó el siguiente código a la API pública. Es importante tener en cuenta aquí que la versión ahora hace referencia al ámbito de la aplicación. Esto contrasta con la etiqueta "@version" de antes, que se limita al bloque de código específico que documenta.
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
