node.jsファイルのドキュメントを書きたいと思ったので,JSDoc3なるものを試してみた.
こんにちは!
ブログに更新したりはしてないのですが,ローカルでnodeのファイルが増え,それぞれが何のファイルだったか思い出せなくなったりしてきたので,ドキュメントを書いていこうと思い,この機会に至りました.
タイトルの通りですが,JSのドキュメント生成ツールとしてのJSDoc3(公式Gitリポジトリ)のインストール&簡単な解説をしていきたいと思います!Javaでいう,JavaDoc(公式(日本語))ですね!
JSDoc3とは
Node.js,Mozilla Rhinoで動作するドキュメント生成ツールです.
Node.jsについては,ver. 3.3.0のものから対応しているそうです.
(今回の解説はNode.jsのみについて書いていきます)
インストール
npm installのコマンドは以下の通りです.
npm install -g git+https://github.com/jsdoc3/jsdoc.git
こちらのコマンドで最新のものをインストールできます.
書き方
基本的に、/** ここにドキュメント本文 */ で記述していきます。
アノテーションを使用して、そのファイルがどのような役割を担っているかを
記述していきます。(例: @callback 、@enum)
使用方法
-g でinstallした方は以下のコマンドでDoc生成が可能です.
jsdoc yourJavaScriptFile.js
そうでない方は.
./node_modules/.bin/jsdoc yourJavaScriptFile.js
という感じで.
すると、同ディレクトリにoutというフォルダができています。
その中のglobal.htmlを見てみてください。
使用例
以下は、線形探索のプログラムのドキュメントを書き、出力したものです。
gyazoで失礼。
見やすいし、簡単に書ける!
アノテーションも豊富で便利っぽい。
以上です!おためしあれ!