web-dev-qa-db-ja.com

JSDocでExpressミドルウェアに注釈を付ける方法は？

Expressミドルウェアをドキュメント化しようとしていますが、WebStormの組み込み検証ツールにより、次のJSDocブロックで型が誤って割り当てられていることがわかります。

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

Expressのソースでは、私を助ける@typedefsが見つかりませんでした。また、@param {*}のようなものは避けたいです。

JSDocを使用してExpressミドルウェアを文書化する正しい方法は何ですか？助けてくれてありがとう。

javascriptexpresswebstormjsdoc
46
Jun Thong

DefinitelyTypedを使用する

  1. エクスプレスタイプをインストールするnpm install --save-dev @types/express
  2. 使用e.Response通常どおり@param {e.Response} res

その他のタイプ

  • ファイル/node_modules/@types/express/index.d.ts
  • Responseの場合e.Responseです：

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

WebStorm

[設定]> [言語とフレームワーク]> [JavaScript]> [ライブラリ]> [@ types/express]からタイプをインストールします

7
Michal Miky Jankovský

まず、ミドルウェアは機能であることに同意します。通常、特別な型宣言は必要ありません。それ以上に、ミドルウェアは高度に分離される傾向があります—modular—これは、通常@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}
 */

ミドルウェアは値を返さないため、スタイルガイドによっては戻りタグはオプションです。最後に、Nickとmmmの主張に反して、nextパラメータは関数です。

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

ミドルウェア関数は、要求オブジェクト（req）、応答オブジェクト（res）、およびアプリケーションの要求/応答サイクル内の次のミドルウェア関数にアクセスできる関数です。 次のミドルウェア関数は、一般的にnextという名前の変数で示されます。

nextは、派手なExpress内部の調合ではありません。 Expressは、次のように、各ミドルウェア関数に要求、応答、およびスタック内の次のミドルウェア関数を渡します。

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

mw1のスコープ内のnextの値はmw2です。

6
jeff_mcmahan

ミドルウェアを文書化できます

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) {}

またはイベントを改善するには、「req」に追加された新しいelemのソースごとにtypedefを作成し、「＆」を使用してそれらすべてを組み合わせたタイプを作成します。

3
Félix Brunet

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){
}
3
Steven Spungin

req、res、およびnextはすべてオブジェクトであり、通常、ミドルウェアは返されないため、以下を使用できます。

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

変更する必要があるのは@param {Function} の隣に @param {Object}。また、@returnは、関数が返すものを説明する必要があります。例：(Object, Array)または組み合わせ({Object|Null})

0
Nick