JsDoc Toolkitによる開発効率向上を目指して

JavaScript開発を見直そう(後編)

JsDoc Toolkitを使いやすくカスタマイズする

遠藤 太志郎
株式会社インテック
ネットワーク&アウトソーシング事業本部

2009/6/18

JavaScriptを使った開発で、ソースの保守性や再利用性までを視野に入れたドキュメントを残しているだろうか。Ajaxを使った高機能なWebサービスなど、JavaScriptによる開発規模は拡大している(編集部)

自分好みのJsDoc Toolkitを構築する

 前編「JsDoc Toolkitによる開発効率向上を目指して」では、JsDoc Toolkitの概要およびJavaScriptの書き方について説明した。

 後編「JsDoc Toolkitを使いやすくカスタマイズする」では、Javaで作られたライブラリであるJsDoc Toolkitを起動し、JavaScript Docを出力するまでに必要な環境設定について解説する。

 最初に、公式サイトからJsDoc Toolkitをダウンロードする。ダウンロードした圧縮ファイルを展開すると「jsdoc-toolkit」というファイルが作成されるので、そのままeclipseに新規プロジェクトとして取り込むと、以下のような状態になる。この中の「JsRun.java」を実行することにより、JavaScript Docsを出力することができる。

●インポート直後のJsDoc Toolkit
インポート直後のJsDoc Toolkit

 しかし、このまま実行するだけではエラーとなるので、引数にJavaScript Docs化するJSファイルのファイルパスや、ファイルの出力場所といった設定を入力して実行する必要がある。次項からは、JsRun.javaを実行するためのオプションの設定方法について解説する。

JsDoc Toolkitセットアップ

 まず設定しなければならないのは、JavaScript Doc化する対象となるJavaScriptを格納しておくためのディレクトリと、出力結果の保存場所である。その場所はどこでもよいのだが、今回は解説用にプロジェクト内に設定する。

 このほか、開発に便利なのでApache Commonsのcommons-collectionscommons-ioを導入し、環境変数に設定する。

 そして、JavaScript Docを出力するために必要なアプリケージョンファイルであるrun.jsと、出力したHTMLのデザインを設定したテンプレートはデフォルトの設定のままで、この情報をプロパティファイルに記述する。

 ここまで設定すると、以下のような状態になる。以降の開発はこの環境で行う。

●環境設定後のJsDoc Toolkit(画像をクリックすると拡大します)
環境設定後のJsDoc Toolkit

実行サポートファイルの作成

 次に、これらの環境を読み込んで、引数としてJsRun.javaに渡すためのJavaファイル「MakeJsDocsAction.java」を作成する。

●MakeJsDocsAction.java
import java.io.File;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import java.util.Properties;

import org.apache.commons.collections.IteratorUtils;
import org.apache.commons.io.FileUtils;

/**
 * JavaScriptDocs作成クラス<br>
 * <br>
 * JavaScriptDocs作成ライブラリ「jsdoc-toolkit」を解析し、<br>
 * 手軽に実行できるように改造したクラスです。<br>
 * 公式サイト: <a href="http://code.google.com/p/jsdoc-toolkit/">http://code.google.com/p/jsdoc-toolkit/</a>
 * 
 * @author Tashiro Endo
 *
 */
public class MakeJsDocsAction {
 
     /**
     * プロパティファイル
     */
    private Properties properties;
 
    /**
     * javaScriptDocs作成<br>
     * <br>
     * プロパティファイルに指定した情報に従い、JavaScriptのDocsを作成する。
     * 
     * @param args
     * @throws IOException 
     */
    public static void main(String[] args) throws IOException {
 
        //インスタンスを作成する。
        MakeJsDocsAction makeJsDocsAction = new MakeJsDocsAction();
 
        //引数を渡してJavaScriptDocsを作成する。
        JsRun.main(makeJsDocsAction.makeArgs());
 
    }
 
    /**
     * コンストラクタ
     */
    public MakeJsDocsAction() throws IOException {
 
        //プロパティファイルの読み込み
        properties = new Properties();
        properties.load(FileUtils.openInputStream(new File("messageresources.properties")));
 
    }
 
    /**
     * 引数作成<br>
     * <br>
     * jsdoc-toolkitに渡す引数を生成する。
     * 
     * @return 引数(args)
     */
    private String[] makeArgs(){
 
        List<String> list = new ArrayList<String>();
 
        //run.jsファイルの設定
        list.add(properties.getProperty("RUN_JS"));
 
        //オプションの追加
        list.add("-a");
 
        //HTMLテンプレートの設定
        list.add("-t="+properties.getProperty("TEMPLATE"));
 
        //出力先ディレクトリの設定
        list.add("-d="+properties.getProperty("OUTPUT_DIR"));
 
        //Docs出力対象JavaScriptの取得
        list.addAll(getDocsJavaScript());
 
        return (String[]) list.toArray(new String[list.size()]);
    }
 
    /**
     * Docs出力対象JavaScriptの取得
     * <br>
     * 指定されたディレクトリ配下の全JavaScriptを取得する。<br>
     * 取得されるのは拡張子が「js」であるもののみ。<br>
     * ディレクトリは階層構造であっても良い。
     * 
     * @return Docs出力対象JavaScriptのパスのリスト
     */
    @SuppressWarnings("unchecked")
    private List<String> getDocsJavaScript(){
 
        List<String> list = new ArrayList<String>();
 
        //Docs出力対象JavaScript格納ディレクトリの取得
        File jsDir = new File(properties.getProperty("JAVASCRIPT_DIR"));
 
        //拡張子の指定
        String[] extensions = {"js"};
 
        //ディレクトリ配下のjsファイルを全件取得する。
        List<File> fileList = (List<File>) FileUtils.listFiles(jsDir,extensions, true);
 
        //jsファイルのパスを取得する。
        Iterator<File> ite = IteratorUtils.getIterator(fileList);
        while(ite.hasNext()){
            list.add(ite.next().getPath());
        }
 
        return list;
 
    }
 
}
 
1/3
next

Index
JsDoc Toolkitを使いやすくカスタマイズする
Page1
自分好みのJsDoc Toolkitを構築する
JsDoc Toolkitセットアップ
実行サポートファイルの作成
  Page2
コンストラクタの設定
オプションの設定
ファイルパス指定
JavaScript Docの出力実行
  Page3
テンプレートの変更
JavaScriptによる開発の未来のために

index Coding Edgeフォーラム トップページ


Coding Edge フォーラム 新着記事
@ITメールマガジン 新着情報やスタッフのコラムがメールで届きます(無料)

注目のテーマ

>

Coding Edge 記事ランキング

本日 月間