Documentar un proyecto con JSDoc en React

JSDoc es un estándar de documentación de código para JavaScript. Proporciona una forma estructurada de agregar comentarios y anotaciones al código para describir su funcionalidad, parámetros, tipos de datos y valores de retorno.

Puedes encontrar más información en la página oficial de JSDoc: jsdoc.app

Sintaxis

Estos son algunos ejemplos que vamos a ver pero hay muchos más (consulta la página oficial)

• @param: Describe un parámetro de una función, indicando su nombre, tipo y una descripcion opcional.
• @returns: Especifica el tipo de valor de retorno de una función.
• @type: Define el tipo de una variable o propiedad
• @description: Proporciona una descripción general del elemento documentado
• @example: Incluye ejemplos de uso o ejemplos de código relacionados con el elemento documentado

Ejemplos de documentación en JSDoc

En el primer ejemplo, podemos ver la descripción de una función, seguida de los parámetros y el valor del retorno

/**
 * Calcula la suma de dos números.
 * @param {number} a - El primer número.
 * @param {number} b - El segundo número.
 * @returns {number} El resultado de la suma.
 */

const addTwoNumbers = (a, b) => a + b

En este ejemplo, vamos a implementar la documentación en un componente de React

import React from 'react'

/**
 * Componente de botón reutilizable.
 * @param {Object} props - Propiedades del componente.
 * @param {string} props.label - El texto del botón.
 * @param {function} props.onClick - Función de manejo de clic del botón.
 * @returns {JSX.Element} El elemento JSX del botón.
 */
function Button({ label, onClick }) {
	return <button onClick={onClick}>{label}</button>
}

Y ahora, veamos cómo se documenta un componente de React utilizando Typescript

import React, { FC, MouseEvent } from 'react'

/**
 * Propiedades del componente Botón.
 * @param {string} label - El texto del botón.
 * @param {function} onClick - Función de manejo de clic del botón.
 */

interface CustomButtonProps {
	label: string
	onClick: (event: MouseEvent<HTMLButtonElement>) => void
}

/**
 * Componente de botón reutilizable.
 * @param {CustomButtonProps} CustomButtonProps
 * @returns {JSX.Element} El elemento JSX del botón.
 */
const CustomButton: FC<CustomButtonProps> = ({ label, onClick }) => {
	return <button onClick={onClick}>{label}</button>
}

export default CustomButton

En resumen, JSDoc nos permite documentar nuestros proyectos de React de manera estructurada y precisa. Al agregar comentarios y anotaciones con las etiquetas adecuadas, podemos describir la funcionalidad, los parámetros, los tipos de datos y los valores de retorno de nuestras funciones y componentes. Esto ayuda a mejorar la comprensión del código y facilita el trabajo en equipo al proporcionar una documentación clara y concisa.