Ejemplo de código para documentación con JSDoc

Introducción

JSDoc Es una herramienta de código abierto para generar documentación de API en JavaScript. Permite a los desarrolladores documentar su código mediante comentarios.

Ejemplo de código para documentación con JSDoc

A continuación se muestra un ejemplo de cómo documentar un método:

/**
* یک فایل را بر اساس شناسه بازیابی می‌کند.
* @param {string} id شناسه فایل.
* @returns {File} شی فایل.
*/
const getFileById = (id) => {
// کد...
}

Instalar JSDoc

Puedes usar JSDoc globalmente usando npm Instalar:

npm install -g jsdoc

O instalar para un proyecto específico de la siguiente manera:

npm install --save-dev jsdoc

Cómo usar JSDoc

Añadir documentación

Para comenzar a documentar su código, simplemente agregue un comentario con /** En la parte superior de cada bloque de código (módulos, métodos, clases, funciones, etc.) agregue:

/**
* کاربر را با استفاده از ایمیل بازیابی می‌کند.
*/
const getByEmail = async (email) => {
// کد...
}

También puedes usar etiquetas JSDoc para agregar más información:

/**
* کاربر را با استفاده از ایمیل بازیابی می‌کند.
* @async
* @method
* @param {String} email - ایمیل کاربر
* @returns {User} شی کاربر
* @throws {NotFoundError} اگر کاربر پیدا نشود.
*/
const getByEmail = async (email) => {
// کد...
}

Producción de documentación

Después de agregar comentarios, para generar la documentación como un sitio web, simplemente ejecute el siguiente comando:

jsdoc path/to/my/file.js

Consejos avanzados

Usando el archivo de configuración

Si su proyecto es grande y contiene muchos archivos y carpetas, puede usar un archivo de configuración para personalizar el comportamiento de JSDoc:

{
"source": {
"includePattern": ".+\\.js(doc|x)?$", // فقط فایل‌های با پسوند .js، .jsdoc یا .jsx پردازش شوند.
"include": ["."], // تمام پوشه‌ها بررسی شوند.
"exclude": ["node_modules"] // پوشه node_modules نادیده گرفته شود.
},
"opts": {
"destination": "./docs/", // مقصد تولید مستندات.
"recurse": true // پوشه‌ها به صورت بازگشتی بررسی شوند.
}
}

Soporte en VSCode

El editor VSCode admite JSDoc de forma predeterminada y ofrece funciones como el autocompletado de estructuras de comentarios y la visualización de información de funciones.

Utilice una plantilla personalizada

Puede anular el formato JSDoc predeterminado creando un archivo diseño.tmpl Personalícelo y especifíquelo en el archivo de configuración.

Resultado

JSDoc es una poderosa herramienta de documentación de código JavaScript que no solo ayuda a los desarrolladores a comprender mejor su código, sino que también proporciona generación automática de documentación API.