JSDOCによるJavaScriptコードの文書化

導入
この投稿では、JSDOCから始めるために知っておくべきことをすべてカバーします.私もあなたと共有するでしょういくつかの他のクールなもの私はそれについては、役に立つかもしれないことを学んだ.

目次

Installation

Usage

Document

Export

Export files or folders

Export all files recursively

Use a configuration file

Other cool stuff about JSDoc

Built-in support in VSCode

Use a custom layout

JSDoc and Swagger

Know any other interesting JSDoc feature?

JSDoc JavaScriptのオープンソースAPIドキュメントジェネレータです.これは、開発者がコメントを介して自分のコードを文書化することができます.以下に例を示します:

/**
 *  Retrieves a single file by id.
 *  @param {string} id File identifier.
 *  @returns {File} File object.
 */
const getFileById = (id) => {
    // ...
}

一旦あなたのコードが完全に文書化されるならば、あなたは簡単なコマンドを実行することによってすべてのAPIドキュメンテーションを含んでいるウェブサイトを簡単に生成することができます.どのようにクールですか?
次のコードは、生成されたウェブサイトでどのように見えるでしょうか


インストール
世界的にJSDOCをインストールするnpm このコマンドを使う

npm install -g jsdoc

または、次のコマンドを使用して単一のプロジェクトにインストールします.

npm install --save-dev jsdoc

インストールの詳細情報here
今、正直に言うと、私はJSDOCのコメントを長い間私のコードを文書化するために使用していたが、数週間前まで私はこのパッケージをインストールしなかった.代わりに、私はちょうどvscodeでそれを使っていました、しかし、私はそれについて話しますlater in this post .

用途

書類
あなたがしなければならないすべてあなたのコードを文書化し始めるために、コメントを加えてください/** モジュール、メソッド、クラス、関数などのドキュメントの各ブロックの上に.
説明を追加するだけで簡単にできます.

/**
 * Retrieves a user by email.
 */
const getByEmail = async (email) => {
    // ...
}

または、タグを使用してJSDocをフルに活用できます.

/**
 * Retrieves a user by email.
 * @async
 * @method
 * @param {String} email - User email
 * @returns {User} User object
 * @throws {NotFoundError} When the user is not found.
 */
const getByEmail = async (email) => {
    // ...
}

があるhuge list of tags あなたのコードをドキュメントとして徹底的にご希望のように選択することができます.
詳細についてはコメントを追加してください.しかし、また、あなたに右に感じる詳細の量を見つける.それはあまりにも多くだったので、維持することができなかったので、すべてのタグを使用して完全に文書化されたいくつかのメソッドを持っているよりもいくつかのタグだけで文書化されたすべてのコードを持っている方が良いです.

エクスポート
コメントを追加したら、ドキュメントのウェブサイトを生成します.

エクスポートファイルまたはフォルダ
単にJSDocを呼び出し、ファイルまたはフォルダーへのパスを追加します.

jsdoc path/to/my/file.js

多くのファイルまたはフォルダを含めるには、単一のスペースで区切られたすべてのパスを追加します.

すべてのファイルを再帰的にエクスポート

jsdoc -r .

設定ファイルを使う
多くのファイルやフォルダをエクスポートしたい大きなプロジェクトに取り組んでいるかもしれません.また、いくつかを除外する必要があります.node_modules ). その場合は、JSDOC設定ファイルを使用してください.
設定ファイルを使用するとJSDocの動作をカスタマイズできます.

どのフォルダやファイルを含めるか除外する.

私たちが使用するとき、JsDocがどれくらい深いかについて--recurse オプション.

テンプレートにカスタマイズを適用する

etc

あなたがする必要があるのは.json 必要な設定を含むファイル-c or --configure JSDocをどこにあるかを指定するオプション

jsdoc -c /path/to/conf.json

以下によく使う例を示します:

{
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",   // Only process file ending in .js, .jsdoc or .jsx
        "include": ["."],                       // Check all folders.
        "exclude": ["node_modules"]             // Be gone, node_modules.
    },
    "recurseDepth": 10,                         // Only go 10 levels deep.
    "opts": {
        "destination": "./docs/",               // Where I want my docs to be generated.
        "recurse": true                         // Same as using -r or --recurse
    }
}

Pro tip:
You may want to add the command to your package.json scripts:

"scripts": {
    "generate-docs": "jsdoc -c /path/to/my/conf.js"
}

その後、単に使用npm run generate-docs コマンドラインから.
または、スクリプトのためのsillier名を使用できます.docs-pls , gimme-docs or ill-have-the-large-docs-with-extra-docs (たぶん,最後のものではないかもしれない😅 ).
設定の詳細情報here

JSDOCに関する他のクールなもの

vscodeの組み込みサポート
それで、私が言ったように、私はそれをインストールする前にさえJSDocを楽しんでいました.

タイプのときにJSDOC注釈構造を構築するスニペット/** 関数の宣言の前にEnterキーを押します.

豊富な情報

あなたがそれを使っているように、機能署名に関する情報

vscodeチェックのjsdocサポートに関する詳細についてはVSCode docs .

カスタムレイアウトを使用する
カスタムドキュメントを作成するには、独自のテンプレートを作成しますlayout.tmpl ファイルとオプションの設定templates.default.layoutFile JSDOC設定ファイルのカスタムレイアウトのパスに.
あなた自身のテンプレートを生成する時間がないか?ここでいくつかのきれいなきちんとしたテンプレートプロジェクトがあります.

Minami

DocStrap

Braintree JSDoc Template

JSDOCとSwagger
このプロジェクトswagger-jsdoc あなたのルートコードのタグ@ swaggerを使用して、あなたのルートのための仕様書を書くことができます.

  /**
   * @swagger
   * /:
   *   get:
   *     description: Returns all users.
   *     responses:
   *       200:
   *         description: All users were returned.
   */
  app.get('/users', (req, res) => {
    // ...
  });

知っている他の興味深いJSDOC機能?
コメントを教えてください!👇