Determinar si vale la pena continuar con la documentación tipo JSDoc

[erikasv]

Descripción y resultado

Determinar si debemos seguir usando la documentación tipo JSDoc en las funciones de los servicios, persistencias y utilitarios del backend (para los servicios en typescript).

Contexto

Desde que empezamos a usar typescript nos hicimos esa pregunta. Y aunque TypeScript tiene implícita la documentación de los tipos de los parámetros y salidas, estaríamos perdiendo la descripción de los mismos y de la función. Sin embargo, estas son prácticamente repetitivas en todas las capas de los servicios, así que puede no ser tan grave.

Lo ideal es buscar si hay alguna recomendación en términos de buenas prácticas con este tema.

Consideraciones

• Angela identificó este mensaje de la extensión de TypeScript del code en la función de capas de portafolios: JSDoc types may be moved to TypeScript types.ts(80004). Creo que esto es por la ausencia en el tipo de retorno en la función, pero que está presente en la documentación. Habría que ignorar el mensaje o poner el tipo de retorno en todas las funciones y debe ser igual al de la documentación (pero esto ya está cubierto al asignar el tipo del objeto que retorna la función del servicio).
• Esta tarea debe tener una ventana de tiempo a dedicar y no extenderla.

[erikasv]

Hey team! Please add your planning poker estimate with Zenhub @cazapatamar @danflop @ManuelStardust @Trjegul84

[ManuelStardust]

Según la información consultada, se concluye que lo mejor es trabajar la documentación con TSDoc. Para esto en la documentación solo se incluyen las descripciones para @param y @return, pero no los tipos, ya que TSDoc los toma de las funciones.

Ej.

/**
 * 
 * @param width - The width of the rectangle.
 * @param length - The length of the rectangle.
 * @returns The area of a rectangle.
 * 
 */

function calcArea(
  width: number | string,
  length: number | string = 20
): number {
  width = Number(width);
  length = Number(length);

  if (isNaN(width) || isNaN(length)) {
    throw new TypeError("Not a number.");
  }

  return width * length;
} 

• Compare JavaScript JSDoc with TypeScript TSDoc for Documentation

• Why You Don't Need Types in JSDoc when Documenting TypeScript

Uso con Eslint Para el funcionamiento de TSDoc con Eslint, es necesario instalar el siguiente plugin: eslint-plugin-tsdoc

[ManuelStardust]

Prueba de Concepto

Se realizó la intalación del plugin de Eslint para TSDoc y se subió a una rama del repositorio del backend: feature/testEslintTSDoc

Ejemplo de resultado de la prueba con eslint

Se realizó la prueba con archivos del back y front de biotablero. A continuación se muestra el resultado de la documentación para la función getData del controlador TargetsController en portafolios.

[ManuelStardust]

Se decidio agregar trabajar con TSDoc y el plugin de Eslint para typescript para el manejo de la documentación del backend, sin embargo la documentación no se va a generar. En el frontend no se trabajara ya que no cuenta con Eslint instalado.