Как комментировать комментарии с помощью JSDoc?

Я пытаюсь документировать промежуточное ПО Express, но встроенный инструмент проверки подлинности в WebStorm сообщает мне, что типы неправильно назначены в следующем блоке JSDoc:

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

В экспресс-источниках я не нашел @typedef, чтобы помочь мне. Кроме того, я хочу избежать таких вещей, как @param {*}.

Каков правильный способ документирования промежуточного ПО Express с использованием JSDoc? Спасибо за любую помощь.

Ответ 1

Во-первых, мы согласны с тем, что промежуточное ПО - это функции; никакое специальное объявление типа обычно не гарантируется. Кроме того, промежуточное программное обеспечение, как правило, сильно разобщено - модульное, что означает, что тег @module обычно применим (и это имеет хорошие последствия при запуске 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}
 */

Возвращаемый тег необязателен в зависимости от вашего руководства по стилю, так как промежуточное ПО не возвращает значение. Наконец, вопреки утверждениям Ника и Ммм, next параметр - это функция.

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

Функции промежуточного программного обеспечения - это функции, которые имеют доступ к объекту запроса (req), объекту ответа (res) и следующей функции промежуточного программного обеспечения в цикле запроса-ответа приложений. Следующая функция промежуточного программного обеспечения обычно обозначается переменной с именем next.

next не выдумка - внутренняя смесь экспресса; Express передает каждой промежуточной функции запрос, ответ и следующую промежуточную функцию в стеке, например так:

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

Значение next в пределах mw1 является mw2.

Ответ 2

Использовать DefinitiveTyped

Установить экспресс-типы npm install --save-dev @types/express
используйте e.Response как обычно @param {e.Response} res

Больше типов

в файле /node_modules/@types/express/index.d.ts
для ответа это e.Response, потому что:

... declare namespace e {... export interface Response extends core.Response { }...

WebStorm

установить типы через Настройки> Языки и рамки> Javascript> Библиотеки> @types/express

Ответ 3

Вы можете не только JsDoc типы параметров и описания, но и их ожидаемые члены.

/**
 * 
 * @module myMiddleware
 * @function
 * @param req {Object} The request.
 * @param res {Object} The response.
 * @param req.params.foo {String} The foo param.
 * @param req.query.bar {String} The bar query.
 * @param req.body {Object} The JSON payload.
 * @param {Function} next
 * @return {undefined}
 */
function foo(req, res, next){
}

Ответ 4

req, res и next - все объекты, а промежуточное ПО обычно не возвращается, поэтому можно использовать следующее.

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

Ответ 5

Единственное, что вам нужно изменить, это @param {Function} рядом с @param {Object}. Кроме того, @return должен описывать, что возвращает функция; например, (Object, Array) или комбинация ({Object|Null})

Ответ 6

Вы можете документировать свое промежуточное программное обеспечение с

const express = require("express");

/**
 * @param {express.Request} req
 * @param {express.Response} res
 * @param {express.NextFunction} next
 */
function (req, res, next) {}

если у вас есть промежуточное ПО, которое добавляет атрибут в req, вы также можете добавить их с помощью

const express = require("express");

/**
 * @param {express.Request & {specialParam1 : string, specialParam2 : any}} req
 * @param {express.Response} res
 * @param {express.NextFunction} next
 */
function (req, res, next) {}

или, что лучше, создайте typedef для каждого источника нового элемента, добавленного в "req", и используйте "&" для создания типа, объединяющего их все.