株式会社ICSGulp15先日、弊社池田が記事「JavaScriptでJSDocコメントを書くメリットとは」でJSDocコメントの有用性についてご紹介しました。その中で「APIリファレンスの書き出し」をメリットの1つとして取り上げていますが、今回はそこをタスクランナーであるgulpを使ってリファレンスのHTMLファイルを自動書き出しする方法をご紹介します。※すでにgulpの環境が構築されている状態を想定してご紹介します。タスクランナーGulpを使ってウェブ制作を爆速にしよう」をご覧ください。gulpを使うのかJSDocの書き出し自体はNode.jsとyuidocjs等で行えるのですが、gulpを使うことで他のタスク(JavaScriptをminifyする等)と一緒に自動化できるというメリットを得られるためです。JSDocを書き出したいプロジェクトのサンプルを下記に用意しました。書き出すHTMLのindex.htmlに流しこむことができるREADME.mdをプロジェクトのルートへ、JSDocコメントが書かれたJavaScriptを「src」フォルダーへ格納してあります。書き出されたHTMLを格納するため「docs」フォルダー格納されます。gulpプラグインをインストールしようまずはJSDocコメントをHTMLに書き出してくれるプラグインであるgulp-jsdocをインストールします。コマンドラインツール(Macならターミナル、Windowsならコマンドプロンプト等)で先ほど用意したフォルダーのルートへ移動し下記のコマンドを実行します。パラメーター・タスクの設定HTMLをどのように書き出したいのかgulp-jsdocのパラメーターを設定します。設定しなくても書き出すことはできるのですが、設定することでHTML内にプロジェクトのバージョンなどを記述したり、HTMLのスタイルを指定できるようになります。下記はgulpのタスクを記述したgulpfile.jsです。HTMLのテンプレートとしてink-docstrapを使用しています。他にも細かくパラメーターを設定できるので興味のある方はご覧ください。こちらはgulp-jsdocをインストールすると同封されるので別途インストールの必要はありません。書き出し!いよいよ書き出しです。下記コマンドを実行してください。gulp「docs」フォルダーにHTMLがずらっと格納されると成功です。先ほどgulpfile.jsで指定したプロジェクト名・バージョンでフォルダーが作成されました。書き出されたindex.htmlをWebブラウザで開くとこのように表示されます。左カラムにREADME.mdの内容が埋め込まれ、右カラムにローカルナビゲーションが設置されています。各クラスのページを開くとパラメーターの説明部分などにテンプレートのスタイルが適応され読みやすくなっています。ソースコードもカラーリングされています。最後にJSDocのHTML書き出しを自動化することでJavaScriptのソースコードとドキュメントに差異もでることなく安心して開発を進められます。今回かかった手間と得られるメリットを比べても断然メリットのほうが大きいかと思います。平成27年11月13日に内容をメンテナンスしています。MEDIAは株式会社ICSが運営するオウンドメディアです。ICSはインタラクションデザイン専門のプロダクション。最先端のwebテクノロジーを駆使し、オンスクリーンメディアの表現分野で活動しています。問い合わせ採用情報インタラクションコンテンツの制作や新しいことに挑戦しながら、互いにスキルを高め合えるメンバーをICSでは募集しています。詳しくは採用情報をご覧ください。MEDIAは古い記事でもメンテナンスし続けることで、常に役立つ情報発信を目指しています。