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

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

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

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

2009/6/18

コンストラクタの設定

 コンストラクタ部分は先に設定したプロパティファイルを読み込んで、グローバル変数にセットする。

 ファイルの出力場所やJavaScriptの置き場所を変えたくなった場合に備えて、ファイルのアドレス指定はベタ書きではなく、プロパティファイルに設定しておくことを推奨する。

 なお、プロパティファイルの読み込みにはapache commonsのFileUtilsを利用した。

●コンストラクタ
    /**
     * コンストラクタ
     */
    public MakeJsDocsAction() throws IOException {
 
        //プロパティファイルの読み込み
        properties = new Properties();
        properties.load(FileUtils.openInputStream(new File("messageresources.properties")));
 
    }

オプションの設定

 Jsdoc-toolkitは、オプションの設定に従ってファイルを作成する。以下にそのオプションの種類のいくつかを紹介する。

タグ 意味
-a JavaScript Docコメントの有無に関わらず、全functionを出力する
-t テンプレートファイルのファイルパス指定
-e ファイルのエンコード。読み込み、書き込み両用。デフォルトはUTF-8になる
-p @privateに設定した機能を出力対象に含める
-d JavaScript Doc出力先
-X 拡張子指定。デフォルトは「.JS」のみ

 具体的なコーディング方法は以下のように行う。

●オプションのセット
    /**
     * 引数作成<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()]);
    }

 各オプションをリストに1つずつセットしていき、最後にリストを配列化した上で、JsRun.javaに送るという方式である。上記のサンプルは、「-a」「-t」「-d」の3つのオプションに加え、さらに出力対象となるJavaScriptのファイルパスを設定したものである。

ファイルパス指定

 出力対象JSファイルのファイルパスの取得と指定は、以下のように行う。

●ファイルパス指定
    /**
     * 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;
 
    }

 JavaScriptディレクトリの中にサブディレクトリを作成し、その中にJSファイルを置いている場合でも、読み込んで出力できる。こうすることによって、JavaScriptのファイル数が増大した場合の管理も容易になる。

 ただし、Javaのようにパッケージ化してdocsを出力できない。JavaScriptディレクトリ中のファイルが一斉に出力されるので、別々のDocsにして出力する場合は、それぞれに出力を実行しなければならない。

JavaScript Docの出力実行

 最後に、作成したパスをJsRun.jsに送り込んで実行する。

●実行
    /**
     * 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());
 
    }

 これで、JavaScript Docの出力は完了である。このように、使い始めるまでは少々手間ではあるが、一度この環境を構築すれば、以降は何度でも簡単に使用することができるのが利点だ。

 ただし、この説明はローカルPCのeclipse内で実行することを前提としたものである。実際の開発現場においては、全員のパソコンにそれぞれこの設定を構築するのは面倒であるので、この「jsdoc-toolkit」プロジェクトをバッチ化して共有サーバなどに保存し、それをメンバー全員で共有して使用するのがよいだろう。

prev
2/3
next

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

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


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

注目のテーマ

>

Coding Edge 記事ランキング

本日 月間