En JSDoc necesitamos incluir comentarios de documentación en el código a través del cual JSDoc generará un sitio web de documentación HTML. Veamos cómo crear comentarios de documentación para diferentes tipos de código.
Strings, números y arrays:
Javascript
/**
* Site Name
* @type {string}
*/
const siteName = "GeeksForGeeks";
/**
* Number
* @type {number}
*/
const number = 1000;
/**
* Array
* @type {Array<number>}
*/
const myArray = [10, 20, 30];
Aquí hemos generado comentarios JSDoc simples con la descripción de las variables y su tipo de datos, que se denota con la ayuda de la etiqueta @type .
Objetos:
Javascript
/**
* Site object
* @type {{id: number, name: string, rank: number|string}}
*/
const site = {
id: 1,
name: "gfg",
rank: 1,
};
En el comentario anterior, hemos especificado el tipo de todas las propiedades de un objeto.
Función/Métodos:
Javascript
/**
* Calculate age
* @param {number} current Current year
* @param {number} yearOfBirth Year of Birth
* @returns {string} your calculated age
*/
const calcAge = (current, yearOfBirth) => {
return `${current - yearOfBirth}`;
};
Aquí, la etiqueta @param se usa para documentar los diferentes parámetros de la función, mientras que la etiqueta @returns documenta el valor de retorno de la función.
Clase:
Javascript
/**
* Class to create new owner
*/
class Owner {
/**
* Owner details
* @param {Object} ownerDetail
*/
constructor(ownerDetail) {
/**
* @property {string} name Owner name
*/
this.name = ownerDetail.name;
/**
* @property {number} age Owner's age
*/
this.age = ownerDetail.age;
}
/**
* @property {Function} printOwner Prints Owner's details
* @returns {void}
*/
printOwner() {
console.log(`Owner's name is ${this.name}
and his age is ${this.age}`);
}
}
Explicación:
- Antes de la declaración de la clase, tenemos un comentario JSDoc para describir la clase.
- Para Constructor, se usa un comentario JSDoc similar a Función
- Dentro del Constructor, para documentar variables, se usa la etiqueta @property
Vinculación de instancia de la clase a su clase
Como hemos creado una clase llamada «Propietario», creemos una instancia de esa clase y vinculémosla a la clase con la ayuda de la etiqueta @link
Javascript
/**
* Link to Owner Class
* See {@link Owner}
*/
const gfg = new Owner({
name: "GeeksForGeeks",
age: 13,
});
Archivo index.js final :
Javascript
// @ts-check
/**
* Site Name
* @type {string}
*/
const siteName = "GeeksForGeeks";
/**
* Number
* @type {number}
*/
const number = 1000;
/**
* Array
* @type {Array<number>}
*/
const myArray = [10, 20, 30];
/**
* Site object
* @type {{id: number, name: string, rank: number|string}}
*/
const site = {
id: 1,
name: "gfg",
rank: 1,
};
/**
* Calculate age
* @param {number} current Current year
* @param {number} yearOfBirth Year of Birth
* @returns {string} your calculated age
*/
const calcAge = (current, yearOfBirth) => {
return `${current - yearOfBirth}`;
};
/**
* Class to create new owner
*/
class Owner {
/**
* Owner details
* @param {Object} ownerDetail
*/
constructor(ownerDetail) {
/**
* @property {string} name Owner name
*/
this.name = ownerDetail.name;
/**
* @property {number} age Owner's age
*/
this.age = ownerDetail.age;
}
/**
* @property {Function} printOwner Prints Owner's details
* @returns {void}
*/
printOwner() {
console.log(`Owner's name is ${this.name} and his age is ${this.age}`);
}
}
/**
* Link to Owner Class
* See {@link Owner}
*/
const gfg = new Owner({
name: "GeeksForGeeks",
age: 13,
});
Salida: Ejecute el siguiente comando jsdoc:
npm run jsdoc
Después de ejecutar el comando, en la carpeta jsdoc, se crearía una página index.html, ábrala en el navegador para ver el sitio de documentación generado por jsdoc.
Salida del sitio de documentación:
Página de inicio del sitio de documentación generado por JSDoc
Documentación de clase de propietario
Algunas etiquetas comunes utilizadas en los comentarios de JSDoc:
- @author: para documentar el autor del código.
- @constant: para documentar constantes.
- @default: permite documentar el valor predeterminado dado a algo.
- @function: esta etiqueta se utiliza para describir la función o el método.
- @global: documenta el objeto global.
- @implements : para documentar la implementación de una interfaz.
- @member: documenta los miembros de la función.
- @module: se utiliza para documentar el módulo de JavaScript.
- @param: esta etiqueta se usa para documentar parámetros/argumentos de la función.
- @returns: se utiliza para documentar el valor de retorno de la función.
- @type – Para documentar el tipo de variables
Publicación traducida automáticamente
Artículo escrito por aniruddhashriwant y traducido por Barcelona Geeks. The original can be accessed here. Licence: CCBY-SA