JSDoc（gulp-jsdoc）でドキュメント生成する方法

node.jsで作成した際に、JSDocをHTMLドキュメントにしたいという要望がありました。いくつかドキュメンテーションモジュールがあるようですがここではjsdocを使用します。

npmモジュールのjsdocをインストールします。

npm i --save-dev jsdoc

モジュール	バージョン
jsdoc	3.6.3

対象のjsファイルが/src/index.jsとします。以下のように実行すると、デフォルトでoutフォルダ配下にドキュメントが生成されます。

npx jsdoc ./src/index.js

package.jsonと同じ場所にconf.jsonというファイルを作成します。(詳細はnpx jsdoc -h)

このJSONファイルに対象ファイルや除外ファイル、出力先などを指定しておくことで細かい設定が可能となります。

{
  "source": {
    "include": ["./src/"] // src配下のjsを対象とする
  },
  "opts": {
    "destination": "./docs/" // docs配下にHTMLを生成する
  }
}

コンフィギュレーションファイルを指定する場合は以下のようにタイプします。

npx jsdoc -c conf.json

これで、src配下の全てのjsファイルのjsdocが生成されます。src配下がさらにディレクトリ構成となっている場合は-rオプションを指定してあげる必要があります。

npx jsdoc -c conf.json -r

jsdocに@access privateと書いた場合、そのメソッドのjsdocはドキュメント生成されないようです。

@returnタグ(@returns)の値を指定していない場合、jsdoc実行時に「@returns tag requires a value」というエラーが出ます。

KHI入社して退社。今はCONFRAGEで正社員です。関西で140-170/80～120万から受け付けております^^
得意技はJS(ES6),Java,AWSの大体のリソースです
コメントはやさしくお願いいたします^^
座右の銘は、「狭き門より入れ」「願わくは、我に七難八苦を与えたまえ」です^^

コメント