【STEP.41】
ドキュメンテーションコメントの使い方をマスターしよう!

ドキュメンテーションコメントとは

コメントは自由に記述ができる反面、人によって書き方がバラバラになってしまい読みづらくなるケースも出てきます。

そこで、ある程度のルールに沿ってコメントを書くことにより可読性を高める方法が提供されています。

それがドキュメンテーションコメントと呼ばれるものです。

ドキュメンテーションコメントは、クラスや関数(メソッド)の直前に記述し、その説明を記載するための、特定のルールに則ったコメントです。

JSDocと呼ばれる専用のツールを介することで、自動的に必要な情報を取り出し、仕様書に整形できます。

ドキュメンテーションとソースとを一元的に管理できることから、メンテナンス性に優れ、両者の矛盾が生じにくいのが特徴です。

以下に、具体的な導入からドキュメント生成までの手順を示します。

導入からドキュメント生成までの手順

【1】Node.jsをインストールする

Node.jsのインストーラーは、Node.js本家サイト(https://nodejs.org/ja/)から入手できます。

ダウンロードしたnode-Ⅴxx.xx.x-x64.msi(xx.xx.xはバージョン番号)をダブルクリックすると、インストーラーが起動します。

あとは、その指示に従って進めていきます。

【2】プロジェクトを作成する

Node.jsを利用した開発では、アプリをプロジェクトという単位で管理するのが一般的です。

ここでは、「c:\data」フォルダー配下に「doc」というフォルダー(プロジェクト)を作成しておきます。

また、プロジェクトフォルダーには、以下のコマンドでpackage.jsonを作成しておきます。

package.jsonはNode.jsの設定ファイルで、アプリの基本情報、依存するライブラリなどを管理します。

> cd c:\data\doc
> npm init -y

-yオプションは、すべて既定の値でpackage.jsonを作成しなさい、という意味です。

-yオプションを指定しなかった場合には、設定ウィザードが起動するので、手動で値を入力することもできます。

既定で生成されたpackage.jsonは、以下の通りです。

{
  "name": "myapp",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

【3】JSDocをインストールする

プロジェクトフォルダーの配下で、以下のコマンドを実行します。

> npm install --save-dev jsdoc

【4】コメント付きの.jsファイルを用意する

ドキュメンテーションコメントとは、「/**~*/」の配下に一定のルールでもって表したコメントのことです。

以下に、ごくシンプルなPersonクラスで例を示します。

ファイルは、/srcフォルダー配下に保存しておきます。

/**
*メンバーに関する情報を管理します。
*@author Ryusei Yokohama
*@version 1.0.0
*/
class Person {
/**
*@param {string} name 名前
*@param {date} birth 誕生日
*@throw {InvalidArgumentsException} birthが日付型ではありません。
*/

constructor(name, birth) {
	
}

/**
*Personクラスの内容を文字列化します。
*@param {Boolean} isDetails 詳細な情報を表示するか
*@returns {String} Personクラスの詳細情報
*@deprecated {@link Person#toString}メソッドを代わりに利用してください。
*/
show(isDetails) {
	
}

/**
*Personクラスに関する詳細情報を表示します。
*@returns {String} メンバーの詳細情報
*/
toString() {
	
}
}

ドキュメンテーションコメントでは、次に掲げる表にあるようなタグを使って、ドキュメント化すべき情報をマークアップします。

【タグの種類】
種類構文記法
スタンドアロンタグ@tag…アスタリスク/空白を除いて、行頭で表すこと
インラインタグ{@tag…}スタンドアロンタグの説明として埋め込める

具体的なタグは、次に掲げる表のようなものがあります。

【JsDoc3で利用できる主なタグ】
タグ概要
@author著者
@constructorコンストラクター関数
@copyright著作権情報
@deprecated非推奨
@example用例
{@link}リンク
@namespace名前空間
@paramパラメータ情報
@defalut既定値
@privateプリベートメンバー
@returns戻り値
@since対応バージョン
@throws例外
@versionバージョン

【5】ショートカットコマンドを定義する

JSDocを実行できるように、package.jsonでnmp scriptsを編集しておきましょう。

これで/srcフォルダー配下のすべての.jsファイルをJSDocでドキュメント化しなさい、という意味になります。

-rオプションは、フォルダー配下のサブフォルダーを再帰的に処理しなさい、という意味です。

{
  "name": "doc",
  ...中略...
  "scripts": {
	"doc": "jsdoc src -r"
   },
  ...中略...
}

【6】ドキュメントを生成する

コマンドラインから以下のコマンドを実行します。

> npm run doc

/srcフォルダーと同列に/outフォルダーができるので、配下のindex.htmlを起動してください。

画面右側のPersonリンクをクリックして、次のようなページが表示されれば、ドキュメント化は成功です。


コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です