Mira el código de abajo. Entonces, tengo un objeto y quiero documentar sus propiedades con jsdoc, por lo que uso la etiqueta @property de jsdoc para documentar esas propiedades de este objeto myObject . Pero también quiero documentar información más compleja, como algunos ejemplos de código, no solo nombres, tipos y descripciones simples.
Pero en la documentación de esta etiqueta @property , dicen que solo podemos agregar esa información simple de nombre o descripciones, y no podemos agregar cosas más complejas (dicen: " no le permite proporcionar @ejemplos o información compleja similar ... . ").
/** * An object with some simple properties * @type {Object} * @property {String} firstProperty This is the first property with a string value * @property {Number} secondProperty This is the second property with a number value */ const myObject = { firstProperty: 'This is the first property', secondProperty: 33, }Y a partir de ahí probablemente ya sepas a lo que me refiero. Quiero preguntar si hay una forma de agregar códigos de ejemplo o información más compleja sobre las propiedades de un objeto usando solo JSDoc. ¡Muchas gracias!
En primer lugar, debo señalar que JsDoc es increíblemente flexible y, lo que es más importante, intentará completar cualquier detalle que necesite que no esté etiquetado explícitamente (como una descripción o tipos de datos) analizando su código y extrayendo lo que necesita.
Pero eso no significa que solo pueda documentar las cosas que JsDoc puede encontrar en su código.
De hecho, puede crear documentación para muchas cosas que no existen explícitamente en su código, si se asegura de que JsDoc tenga todo lo que necesita para producir documentación.
Como mínimo, cada objeto "documentable" debe tener un nombre y tal vez una relación con otro objeto.
Presumiblemente, su objeto está documentado en un módulo, por lo que siempre puede agregar ejemplos a la sección @module de su doclet de nivel superior como:
/** * Encapsulates the concept of a Widget. * * @example * * // assuming we have previously instantiated a disp:Display * * var opts = { ... }; * * var w = new Widget(opts); * * w.displayOn(disp); * * @module */O bien, puede agregar su documento a un elemento con nombre que no existe, como en:
/** * Example of how to use the Object properties. * * @name ObjectPropertyExample * @memberof MyObject * * @example * ... */ En jsdoc, cualquier cosa a la que le dé un @name se incluirá en su documentación.
Y si agrega una etiqueta @memberof , puede asignar su nueva entidad a otro objeto definido o incluso asignarla a objetos que crea sobre la marcha.
Si no agrega una etiqueta @memberof , el elemento se asociará con el objeto "global" abstracto.
El ejemplo anterior creará una referencia a MyObject~ObjectPropertyExample en sus documentos.
Si te dicen "no puedes". Literalmente no puedes. 🤷♂️