Web Components 開発におけるドキュメント同時生成手法の提案 1
はじめに HTML5 の登場 Web 上で可能な表現や操作の増加 開発まわりも大きく変化 2
はじめに ソフトウェア開発手法の輸入 データバインディング MVVM(Model/View/ViewModel) モデル タスクランナー Grunt/Gulp.js ECMAScript2015 etc 3
Web Components Web ページの構成要素をコンポーネント化 Web 標準の技術となる予定 3 つの仕様で構成 Shadow DOM Custom Elements HTML Imports Google Chrome や Polyfill ライブラリの使用で利用することが可能 4
Web Components 利点 独自タグの定義および使用 必要なリソースの一括ロード コンポーネントの利用の簡単化 マークアップ構造 スタイルのカプセル化 競合問題とそれに対する対策コストの削減 ID の重複 ( クラスの重複による ) デザイン指定の競合 5
Web Components 例 Twitter の Like ボタン 6
Web Components 例 Twitter の Like ボタン JavaScript ライブラリの場合 <div class="twitter-like-button" animate liked value="13203"> </div> <script> var container = document.queryselector( ); TwitterLikeButton.setup(container); </script> 7
Web Components 例 Twitter の Like ボタン Web Components 化で例えば次のような簡潔な記述で使いまわせるように <twitter-like-button animate liked value="13203"> </twitter-like-button> 8
Web Components 実体 1 つの HTML ファイルとして提供 コンポーネント化部分のマークアップ マークアップに対するデザイン指定 (CSS) 動作や API などの定義 (JavaScript) 9
Web Components 実体 <template> <style>/* デザイン指定 */</style> <!-- コンポーネント化するマークアップ --> </template> <script> var proto = Object.create( ); // 動作 API の定義 var Tag = document.registerelement( "tag-name", {prototype: proto}); </script> 10
問題点 ユーザ向けの (API) ドキュメントの作成 現状ドキュメント単体を個別に作成するか コードそのものをドキュメントとしている 従来から使われている手法が使えない ドキュメントコメント 文芸的プログラミング 11
従来手法 ドキュメントコメント コード中に記述した特殊なコメントを解析しドキュメントを生成する方法 Java における JavaDoc など広く活用される /** * メソッドの説明 * @param arg 引数の説明 * @return 戻り値の説明 */ public int funcname(int arg){ } 12
従来手法 ドキュメントコメント 正規化されたドキュメントを作成可能 元来 単一の言語のコードに対して使われる 複数の言語が混在している状況では使えない API に対する記述以外の内容はどこに載せるのが適当か ライセンスや制作者など 13
従来手法 文芸的プログラミング Knuth が提唱するプログラミングスタイル ドキュメントを記述しながらコーディング @* セクション名コードに対する説明 @< コード断片の定義 @>= コード断片 14
従来手法 文芸的プログラミング 複数の言語の存在するコードでも対応可能 出力されるドキュメントの形式がユーザ向けのドキュメントではない ドキュメントコメント方式と比較して より書き方に依存するドキュメントが生成される 15
目的 1 つの記述で 1 つの Web Components のコードとドキュメントを同時生成 これを行うツールの作成 有用性の検証 16
着眼点 ドキュメントコメント 書き方がある程度決まっている 一定の内容の出力を保証 文芸的プログラミング 複数の言語が混在していても問題ない 自由度の高い記述が可能 両者の強みを活かす 17
提案手法 ドキュメントのなかにコードを埋め込む 埋め込まれたコードとドキュメントの内容を合わせて 1 つの完成したコードを生成 コードなどの不要な部分の除去を行った上ユーザドキュメントを生成する 18
提案手法 記述例 ## style Explanation of style..box { background: yellow; } p { font-weight: bold; font-size: 16px; } ## structure Explanation of structure <div class="box"> <p>foo bar</p> </div> 19
提案手法 記述例 ## properties propertyname1 : `"initial value"` : type String Explanation of propertyname1 propertyname2 : type Number : `1234567890`... 20
提案手法 記述例 ## methods functionname : param {type} arg1 explanation : param {type} [arg2] explanation : return {type} explanation on return value Explanation of functionname // definition of function return arg1 + (arg2 0); 21
提案手法 概念図 ドキュメントのなかにコードを埋め込む 22
提案手法 概念図 埋め込まれたコードとドキュメントの内容を合わせて 1 つの完成したコードを生成 23
提案手法 概念図 コードなどの不要な部分の除去を行った上ユーザドキュメントを生成する 24
ドキュメント記法 ドキュメントをどの記法で記述するか 以下のような条件を満たすべき 記述が容易 素の状態で読みやすい 最低限の文書構造を記述可能 プログラムコードの埋め込みが可能 可能ならばよく知られた汎用的な記法 25
Markdown 記法 Gruber が提唱する簡易マークアップ言語 テキストメールの装飾に似た記法 Web を中心に広く活用されてる GitHub でのドキュメント (ReadMe) ブログの記事の編集 WordPress/Octopress/ はてなブログ 26
Markdown 記法 # 見出し レベル 1 ## 見出し レベル 2 空行までが 1 段落になる _ 強調 _ などの ** テキスト装飾 ** も行える ```javascript console.log(" プログラムコードも埋め込み可 ") ``` - リスト記法なども - 用意されている 27
書式 レベル 1 の見出しをタグ名としてタイトル代わりに使用する 見出しから見出しまでをセクションとしてレベル 2 のセクションに各種定義をしていく # tag-name ## section title section contents ## section title section contents 28
書式 マークアップ スタイル マークアップはstructureセクション スタイル指定はstyleセクション セクション中のコードを抽出して利用 その他の内容は使用しない 29
書式 マークアップ スタイル ## style Explanation of style. スタイル定義.box { background: yellow; } p { font-weight: bold; font-size: 16px; } ## structure Explanation of structure <div class="box"> <p>foo bar</p> </div> 30
書式 マークアップ スタイル ## style Explanation of style..box { background: yellow; } p { font-weight: bold; font-size: 16px; } ## structure Explanation of structure マークアップ定義 <div class="box"> <p>foo bar</p> </div> 31
書式 マークアップ スタイル ## style Explanation of style..box { background: yellow; } p { font-weight: bold; font-size: 16px; } ## structure Explanation of structure <div class="box"> <p>foo bar</p> </div> 埋め込みコード 32
書式 プロパティ定義 properties セクションで定義 定義リスト記法で定義 用語をプロパティ名とする 定義には型や初期値などを指定 次に定義リストが現れるまでの内容は前の定義リストのプロパティに対する説明 33
書式 プロパティ定義 ## properties propertyname1 : `"initial value"` : type String 1 つのプロパティの定義 Explanation of propertyname1 propertyname2 : type Number : `1234567890`... 34
書式 プロパティ定義 ## properties propertyname1 : `"initial value"` : type String プロパティ名 Explanation of propertyname1 propertyname2 : type Number : `1234567890`... 35
書式 プロパティ定義 ## properties propertyname1 : `"initial value"` : type String 初期値 Explanation of propertyname1 propertyname2 : type Number : `1234567890`... 36
書式 プロパティ定義 ## properties propertyname1 : `"initial value"` : type String 型名 Explanation of propertyname1 propertyname2 : type Number : `1234567890`... 37
書式 プロパティ定義 ## properties propertyname1 : `"initial value"` : type String Explanation of propertyname1 説明 propertyname2 : type Number : `1234567890`... 38
書式 メソッド定義 methods セクションで定義 プロパティ同様 定義リスト記法で定義 次に定義リストが現れるまでの内容のうちで最後に現れるコードを処理内容とする 39
書式 メソッド定義 ## methods functionname メソッド名 : param {type} arg1 explanation : param {type} [arg2] explanation : return {type} explanation on return value Explanation of functionname // definition of function return arg1 + (arg2 0); 40
書式 メソッド定義 ## methods functionname : param {type} arg1 explanation 引数の定義 : param {type} [arg2] explanation : return {type} explanation on return value Explanation of functionname // definition of function return arg1 + (arg2 0); 41
書式 メソッド定義 ## methods functionname : param {type} arg1 explanation : param {type} [arg2] explanation : return {type} explanation on return value Explanation of functionname 戻り値の説明 // definition of function return arg1 + (arg2 0); 42
書式 メソッド定義 ## methods functionname : param {type} arg1 explanation : param {type} [arg2] explanation : return {type} explanation on return value Explanation of functionname メソッド全体の説明 // definition of function return arg1 + (arg2 0); 43
書式 メソッド定義 ## methods functionname : param {type} arg1 explanation : param {type} [arg2] explanation : return {type} explanation on return value Explanation of functionname // definition of function return arg1 + (arg2 0); メソッドの処理内容 44
書式 メタ情報の記述 YAML Front Matter で記述 広く使われている手法 著者情報や依存関係の記述に使用 後述のツールの動作指定にも利用 45
書式 その他の記述 以下について定義可能 ライフサイクルコールバック テストコード デモコード 具体的な記法は想定していないが その他自由に内容を記述することが可能 46
実装 Node.js 上で動作する CLI として実装 Polyfill ライブラリ (Polymer) の使用を想定したコードを出力する HTML 形式の API ドキュメントを出力 github.com/e8l/wcweb 47
実装 動作フロー 1. YAML Front Matterの解析 2. Markdownの解析 AST 作成 3. コードの抽出 内容の解析 4. コードの生成 5. ASTの整形 6. ドキュメントの出力 48
実装 AST 作成 Pandoc を用いて JSON 形式の AST を取得 さらに DOM に似せたデータ構造へ変換 解析や整形を行いやすくするため 49
実装 コード生成 テンプレートエンジンを用いて作成 Mustache というエンジンを使用 ひな形とドキュメントの記述から外枠を作り 抽出したコード片と組み合わせる 50
実装 AST 整形 ドキュメント出力 API ドキュメントとして不必要な内容を除去 実装に用いるコードやテストコード 更新履歴やインストール方法 整形後の AST を JSON 形式に逆変換して Pandoc を用いてドキュメントを出力 更新履歴などは ReadMe テキストへ出力 51
実装 外部ツール連携 YAML Front Matter 部でタスクを指定 Lint や難読化などを別ツールを用いて実行 代替言語を用いた作成 HTML や CSS は代わりに Haml や SCSS などを使用して記述可能 オプションで CoffeeScript を使用することも可能 52
考察 仕様策定段階にあることについて あまりにも大きな変更は恐らくない HTML CSS JavaScript を同時に扱うならば出力形式変更で対処可能 53
考察 対象の拡大について 手法自体は文芸的プログラミングと同様に言語によらず使用可能 ドキュメント駆動開発や Readme 駆動開発との親和性が高い 54
考察 エディタのサポート いくつかのエディタはシンタックスハイライト可 55
VIM 56
Atom 57
考察 エディタのサポート いくつかのエディタはシンタックスハイライト可 コードの補完やインテリセンスは未サポート 専用エディタやプラグインを新たに用意する必要 58
考察 Markdown によるドキュメントの記述 ドキュメントの記述性を阻害する可能性 文書構造に意味をもたせているため 独自記法の導入か用いる文書構造の調整が必要になる可能性がある 59
今後の展望 定量的 定性的な有用性の検証 提案手法の応用分野の検討 Web Components 以外の作成に使用可能か 教育などへの利用ができないか 60
関連研究 Web Components Cascading Tree Sheet[2][3] Benson らが提唱するコンポーネント化手法 CSS に似た構文で記述 SmartComposition[5] Web Components を用いた研究 マルチデバイス向けのマッシュアップライクな Web アプリケーション作成を容易に 61
関連研究 Markdown Madoko[7] 複雑なドキュメントのためのオーサリングツール RUMU Editor[8] フレームワークを用いて Web ページを作成 API Blueprint WebAPI の記述とドキュメント作成 62