チュートリアル（基本編） » 08.ドキュメント記述・生成(JSDoc)

08.ドキュメント記述・生成(JSDoc)

Last modified by kashi on 2017/03/27, 11:28

チュートリアル目次

概要
- JSDocを書く理由
準備
- Eclipseの設定方法
- JSDoc入力時、memberOfタグを自動補完する方法
よく使用するタグについて
JSDocの書き方
記述例
出力方法
出力結果
- hifive本体での利用
補足
参照

概要

このページでは、JSDoc3を使ったドキュメント生成に適した一般的なコントローラ、ロジックの定義について記述します。

JSDocを書く理由

eclipse上で、ソースコードに記述したJSDocを元にコード入力中に補完候補を表示したり、
アウトラインにクラス名や型の一覧を詳細に表示させることができる様になります。
また、JSDocからHTML形式の、APIドキュメントを出力することもできます。
これにより、コード自体の可読性、コーディング作業や保守が容易になります。

準備

Eclipseの設定方法

日本語版
- ウィンドウ -> 設定 -> JavaScript -> バリデーター -> JSDoc -> 『JSDoc のコメント処理 (検索およびリファクタリングを含む)』をチェック

英語版
- Window -> Preferences -> JavaScript -> Validator -> JSDoc -> 『Process JSDoc comments』をチェック

開発プロジェクトについて
JavaScript開発ではJavaScriptプロジェクトとしてプロジェクト作成します。
- 新規JavaScriptプロジェクトの作成
  - 新規 -> その他 -> JavaScript -> JavaScriptプロジェクト
- 既存プロジェクトをJavaScriptプロジェクトに変更
  - プロジェクト右クリック -> 構成 -> JavaScriptプロジェクトへ変換

JSDoc入力時、memberOfタグを自動補完する方法

以下の順番で設定を行うことにより、/** */ を入力すると、@memberOf <namespace> が自動補完されます。

プロジェクトのコンテキストメニュー -> プロパティ -> JavaScript -> コード・スタイル -> コード・テンプレートを開く。
（コンテキストメニューは、プロジェクト・エクスプローラーでプロジェクトのアイコンを右クリックすると出せます。）
プロジェクト固有の設定を可能にする。にチェックを入れる。
インポートを押下。
コードテンプレートXMLを指定してOKボタンを押下。

※コードテンプレートXMLのサンプルはこちら (右クリック⇒保存)

@memberOfを１つ以上記述しないと、アウトライン候補に表示されないため注意。

よく使用するタグについて

@memberOf 名前空間名orクラス名	どのプロパティに所属しているか定義する。
@name プロパティ名	プロパティ名を定義する。未指定の場合はコードで定義された名前がプロパティ名となる。また、@memberOfが指定されているとそのメンバに紐付く。
@namespace	名前空間を定義する。未指定の場合はメンバとして処理される。
@param {型名} 引数名	引数の名前と型が定義する。
@type 型名	変数の型を定義する。
@returns {型名} コメント	戻り値の詳細を定義する。
@class	クラスとして定義する。
@instance	インスタンスメンバとして定義する。記述しない場合はstaticメンバになる(@staticで明示的に指定することも可)。

JSDocの書き方

コントローラ
- オブジェクト自身に @class と @name xxxController と @memberOf をつける。
- プロパティには @memberOf を付ける。必要に応じて@type、@paramや@returns等を書く。

ロジック
- オブジェクト自身に @class @name xxxLogic と @memberOf をつける。
- プロパティには @memberOf を付ける。必要に応じて@type、@paramや@returns等を書く。

記述例

SampleControllerはsample.controller、SampleLogicはsample.logicを@memberOfで指定しています。この指定先は名前空間であり、Javaで言うパッケージ名のようなものです。名前空間は以下のような記述で定義し、JSDoc生成対象のファイルのどこかに記述する必要があります。

/**
* @namespace sample
*/
/**
* @namespace sample.controller
*/
/**
* @namespace sample.logic
*/

注意：sampleの定義をせずにsample.xxxの名前空間を定義することはできません。

出力方法

JSDoc 3.4以降の場合

node.jsをインストールする
jsdocをインストールしたいフォルダでコマンドプロンプトで移動する
npmでjsdocをインストールする
npm install jsdoc

インストールしたフォルダでjsdocコマンドを実行する
.\node_modules\.bin\jsdoc yourJavaScriptFile.js

outフォルダにJSDocが生成される

例:JSDocが記述されたJSファイルが C:\src 配下にある場合。

.\node_modules\.bin\jsdoc C:\src -r

また、 -dオプションを指定することで、出力先のディレクトリを指定することもできます。

.\node_modules\.bin\jsdoc [出力したいJSファイルが格納されているディレクトリパス] -r -d [出力先のディレクトリパス]

例:JSDocが記述されたJSファイルが C:\src にあり、出力先のディレクトリは C:\dist とする場合。

.\node_modules\.bin\jsdoc C:\src -d C:\dist

出力先を指定しない場合、jsdoc.jsと同じフォルダ(ここではC:\jsdoc)に out フォルダが作成され、その中にドキュメントが生成されます。

上記設定は、jsonファイルとして作成した設定ファイルを指定することでも対応できます。

{
   "source": {
       "include": ["C:/jsdoc"]
    },
   "opts": {
       "template": "templates/default",
       "destination": "C/dist",
       "recurese": true,
       "private": false
    },
   "templates": {
       "default": {
           "useLongnameInNav": true
        }
    }
}

上記ファイルをjsdoc.jsonとして保存し、以下のコマンドを実行します。

.\node_modules\.bin\jsdoc -c jsdoc.json

JSDoc 3.3以前の場合

手順は以下のとおり。

github：jsdoc からJSDocのモジュールをダウンロードする。
ダウンロードしたzipを解凍し適当な場所に置く。(ここでは、フォルダ名を『jsdoc』、場所はCドライブ直下に置いたものとして説明します)
コマンドプロンプトを開き、C:\jsdoc に移動する。
以下のコマンドを実行し、JSDocを出力します。
java -jar lib/js.jar -modules node_modules -modules rhino_modules ./jsdoc.js [出力したいJSファイルが格納されているディレクトリパス]

例:JSDocが記述されたJSファイルが C:\src 配下にある場合。

java -jar lib/js.jar -modules node_modules -modules rhino_modules ./jsdoc.js C:\src

また、 -d または -destination オプションを指定することで、出力先のディレクトリを指定することもできます。

java -jar lib/js.jar -modules node_modules -modules rhino_modules ./jsdoc.js [出力したいJSファイルが格納されているディレクトリパス] -d [出力先のディレクトリパス]

例:JSDocが記述されたJSファイルが C:\src にあり、出力先のディレクトリは C:\dist とする場合。

java -jar lib/js.jar -modules node_modules -modules rhino_modules ./jsdoc.js C:\src -d C:\dist

出力先を指定しない場合、jsdoc.jsと同じフォルダ(ここではC:\jsdoc)に out フォルダが作成され、その中にドキュメントが生成されます。

その他オプション一覧

オプション	説明
-t or --template <value>	The name of the template to use. Default: the "default" template
-c or --configure <value>	The path to the configuration file. Default: jsdoc dirname + /conf.json
-e or --encoding <value>	Assume this encoding when reading all source files. Default: utf-8
-q or --query <value>	Provide a querystring to define custom variable names/values to add to the options hash.
-T or --test	Run all tests and quit.
-d or --destination <value>	The path to the output folder. Use "console" to dump data to the console. Default: console
-p or --private	Display symbols marked with the @private tag. Default: false.
-r or --recurse	Recurse into subdirectories when scanning for source code files.
-h or --help	Print this message and quit.
-X or --explain	Dump all found doclet internals to console and quit.