JSDoc generalmente se usa para especificar metadatos para el código javascript y se puede usar para generar documentación automáticamente. Ver: https://jsdoc.app/about-getting-started.html

Ejemplo:

 /** * @author Some Guy <example@example.com> * @see {@link https://jsdoc.app/tags-description.html} for further information. * @description How to use JSDoc to tag javascript. */

No hay una forma oficial de especificar esto. Al menos no hay un Camino Verdadero.

Dicho esto, el más aceptado son los comentarios de JSDoc . Debe comenzar un comentario de bloque con /** (dos asteriscos) y luego puede usar la sintaxis especial de JSDoc para explicar su fuente con @author y @see :

 /** * Function that returns a random number * @author Jon Skeet * @see {@link https://stackoverflow.com/a/11373465} * * @param {number} min - minimum bound (inclusive) * @param {number} max - maximum bound (inclusive) * @return {string} - uniformly distributed integer within the range as a string */ function rand(min, max){ return (Math.floor(Math.random() * (max - min + 1)) + min).toFixed(0); }

¿Quizás incluso legible por máquina?

JSDoc es legible por máquina. Hay muchas herramientas que lo consumen. En particular, muchos editores de JavaScript estándar como Visual Studio Code le darán el JSDoc para una función al pasar el mouse.

Sin embargo, existen otras herramientas que pueden consumir JSDoc o un subconjunto de este. Pueden producir documentación o realizar una verificación de tipos en función de lo que se especifica para @param y @return u otras tareas.

También vale la pena señalar que no necesita tener ninguna herramienta para usar JSDoc. Puede escribirlo directamente en su código fuente incluso si nunca se consume. Todavía puede ser leído por otros humanos que lo entiendan. Incluso si es la primera vez que se encuentran con el estilo de documentación, es lo suficientemente sencillo como para entenderlo fácilmente.