javascript - exports - Cómo anotar Express middlewares con JSDoc?

jsdoc object properties

Question

Estoy intentando documentar un middleware Express, pero la herramienta de validación incorporada en WebStorm me dice que los tipos están asignados incorrectamente en el siguiente bloque JSDoc:

/**
* My middleware.
*
* @param {Object} req
* @param {Object} res
* @param {Function} next
* @return {Object}
*/
exports.show = function(req, res, next) {
...
};

En las fuentes Express, no encontré ningún @typedef para ayudarme. Además, quiero evitar cosas como @param {*} .

¿Cuál es la forma correcta de documentar el middleware Express utilizando JSDoc? Gracias por cualquier ayuda.

Answer 1

Lo único que necesita cambiar es @param {Function} junto a @param {Object} . Además, @return debería describir lo que devuelve la función; ej., (Object, Array) o una combinación ({Object|Null})

Answer 2

Primero, aceptamos que el middleware son funciones; no se justificará ninguna declaración de tipo especial. Más allá de eso, el middleware tiende a estar altamente desacoplado, es modular, lo que significa que la etiqueta @module generalmente es aplicable (y esto tiene buenas consecuencias cuando ejecuta jsdoc).

/**
* Description of my middleware.
* @module myMiddleware
* @function
* @param {Object} req - Express request object
* @param {Object} res - Express response object
* @param {Function} next - Express next middleware function
* @return {undefined}
*/

La etiqueta de devolución es opcional dependiendo de su guía de estilo, ya que el middleware no devuelve un valor. Finalmente, al contrario de lo que afirman Nick y mmm, el next parámetro es una función.

http://expressjs.com/en/guide/using-middleware.html

Las funciones de middleware son funciones que tienen acceso al objeto de solicitud (req), el objeto de respuesta (res) y la siguiente función de middleware en el ciclo de solicitud-respuesta de la aplicación. La siguiente función de middleware comúnmente se denota por una variable llamada siguiente.

next no es un brebaje de Express interno; Express pasa a cada función de middleware la solicitud, la respuesta y la siguiente función de middleware en la pila, así:

mw1 = function(req, res, next){}.bind(undefined, req, res, mw2)
mw2 = function(req, res, next){}.bind(undefined, req, res, mw3)

El valor de next dentro del alcance de mw1 es mw2 .

Answer 3

req , res y next son todos objetos, y un middleware por lo general no regresa, por lo que se puede usar lo siguiente.

/**
* My Middleware
* @name MyMiddleWare
* @function
* @param {Object} req
* @param {Object} res
* @param {Object} next
*/