131 lines
2.7 KiB
Markdown
131 lines
2.7 KiB
Markdown
# [Javascript][JSDoc]ドキュメントを自動生成する(TypeScript対応)
|
|
|
|
* JSDocコメントの有効活用
|
|
* JavaScriptやTypeScriptのドキュメントを生成する方法
|
|
|
|
- [\[Javascript\]\[JSDoc\]ドキュメントを自動生成する(TypeScript対応)](#javascriptjsdocドキュメントを自動生成するtypescript対応)
|
|
- [インストール方法](#インストール方法)
|
|
- [packeage.jsonの設定](#packeagejsonの設定)
|
|
- [TypeScriptの場合](#typescriptの場合)
|
|
- [書き方について](#書き方について)
|
|
- [ファイルを出力する](#ファイルを出力する)
|
|
- [1つの対象ファイルを出力する](#1つの対象ファイルを出力する)
|
|
- [markdownで出力する場合](#markdownで出力する場合)
|
|
- [HTMLで出力する場合](#htmlで出力する場合)
|
|
|
|
|
|
## インストール方法
|
|
|
|
```sh
|
|
npm install jsdoc -D
|
|
```
|
|
|
|
### packeage.jsonの設定
|
|
|
|
スクリプトを記載する
|
|
`-r`オプションを用いて、出力させたい対象のフォルダーを指定します
|
|
|
|
```json
|
|
{
|
|
"scripts": {
|
|
"doc": "jsdoc -r src"
|
|
}
|
|
}
|
|
```
|
|
|
|
### TypeScriptの場合
|
|
|
|
インストール方法
|
|
|
|
```sh
|
|
npm install typedoc -D
|
|
```
|
|
packeage.jsonの設定
|
|
|
|
```json
|
|
{
|
|
"scripts": {
|
|
"doc": "typedoc --entryPointStrategy expand ./src"
|
|
}
|
|
}
|
|
```
|
|
|
|
tsconfig.jsonファイルの設定
|
|
|
|
```json
|
|
{
|
|
"compilerOptions": {
|
|
"module": "ESNext",
|
|
"target": "ESNext",
|
|
"sourceMap": true,
|
|
"strict": true
|
|
},
|
|
"exclude": [
|
|
"node_modules"
|
|
]
|
|
}
|
|
```
|
|
|
|
## 書き方について
|
|
|
|
JSDocはJavascriptのコメントルールです
|
|
VSCodeとの相性が良い。プラグインなしで自動で生成できる
|
|
|
|
* コメントが必要なところで`/**`を入力すると自動的に生成される
|
|
* autocompleteが自動に表示しますので、`Enter`を入力する
|
|
|
|
```js
|
|
/**
|
|
```
|
|
|
|
## ファイルを出力する
|
|
|
|
### 1つの対象ファイルを出力する
|
|
|
|
#### markdownで出力する場合
|
|
|
|
**markdownのモジュールをインストール**
|
|
|
|
```sh
|
|
npm install -g jsdoc-to-markdown
|
|
```
|
|
|
|
**ファイルを出力する**
|
|
|
|
```sh
|
|
npx jsdoc-to-markdown your-file.js > output.md
|
|
# npx jsdoc-to-markdown src/script/sampleScript.js > output.md
|
|
```
|
|
|
|
#### HTMLで出力する場合
|
|
|
|
**ファイルを直接指定する場合**
|
|
|
|
```sh
|
|
jsdoc your-file.js -d doc
|
|
# jsdoc src/script/sampleScript.js -d docments
|
|
```
|
|
|
|
**設定ファイルを仕様する場合**
|
|
|
|
|
|
`jsdoc.json`を生成する
|
|
|
|
```json
|
|
{
|
|
"source": {
|
|
"include": ["src/script/sampleScript.js"]
|
|
},
|
|
"opts": {
|
|
"destination": "./docments"
|
|
}
|
|
}
|
|
```
|
|
|
|
**ファイルを出力する**
|
|
|
|
```sh
|
|
jsdoc -c jsdoc.json
|
|
```
|
|
|