js-common-code/docs/jsDoc.md

[Javascript][JSDoc]ドキュメントを自動生成する(TypeScript対応)

• JSDocコメントの有効活用
• JavaScriptやTypeScriptのドキュメントを生成する方法

• [Javascript][JSDoc]ドキュメントを自動生成する(TypeScript対応)
  • インストール方法
    • packeage.jsonの設定
    • TypeScriptの場合
  • 書き方について
  • ファイルを出力する
    • 1つの対象ファイルを出力する
      • markdownで出力する場合
      • HTMLで出力する場合

インストール方法

npm install jsdoc -D

packeage.jsonの設定

スクリプトを記載する -rオプションを用いて、出力させたい対象のフォルダーを指定します

{
    "scripts": {
        "doc": "jsdoc -r src"
    }
}

TypeScriptの場合

インストール方法

npm install typedoc -D

packeage.jsonの設定

{
    "scripts": {
        "doc": "typedoc --entryPointStrategy expand ./src"
    }
}

tsconfig.jsonファイルの設定

{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ESNext",
    "sourceMap": true,
    "strict": true
  },
  "exclude": [
    "node_modules"
  ]
}

書き方について

JSDocはJavascriptのコメントルールです VSCodeとの相性が良い。プラグインなしで自動で生成できる

• コメントが必要なところで/**を入力すると自動的に生成される
• autocompleteが自動に表示しますので、Enterを入力する

/**

ファイルを出力する

1つの対象ファイルを出力する

markdownで出力する場合

markdownのモジュールをインストール

npm install -g jsdoc-to-markdown

ファイルを出力する

npx jsdoc-to-markdown your-file.js > output.md
# npx jsdoc-to-markdown src/script/sampleScript.js > output.md

HTMLで出力する場合

ファイルを直接指定する場合

jsdoc your-file.js -d doc
# jsdoc src/script/sampleScript.js -d docments

設定ファイルを仕様する場合

jsdoc.jsonを生成する

{
  "source": {
    "include": ["src/script/sampleScript.js"]
  },
  "opts": {
    "destination": "./docments"
  }
}

ファイルを出力する

jsdoc -c jsdoc.json