web components 開発における...
TRANSCRIPT
平成２７年度修士論文
Web Components開発におけるドキュメント同時生成手法
情報・通信工学専攻コンピュータサイエンスコース
１４３１０１７海老澤雄太
主任指導教員 寺田実 准教授 指導教員 岩崎英哉教授
提出日２０１６年１月２９日
1
概要
目的
Web上での表現の発展に従い，Webにおける開発手法も変化してきた．様々な技術や開発ツールが現れる
中，Web Componentsという仕様が登場した．現在は仕様策定段階にある，Webページを構成する要素をコン
ポーネントとして定義し再利用するための仕組みで，今後のWeb開発における重要な技術として位置づけら
れると考えられる．
コンポーネントを作成するにあたり，提供する APIやその使い方を記したドキュメントを用意することは重
要である．従来，ドキュメントを作成するコストを削減するために，ソースコードと同時生成する手法が用い
られてきた．その例として，ソースコード中の特殊なコメント，ドキュメントコメントから情報を抽出してド
キュメントを生成する手法などが挙げられる．しかしながら，Web Componentsではドキュメントコメントを
用いる方法をはじめ，従来手法を用いたドキュメント生成を行うことができない．そのため，Web Components
の開発者は，ソースコードとドキュメントとを個別に作成しなければならない．
そこで，本研究ではWeb Componentsに対し，そのソースコードとドキュメントを同時生成するための手法
を提案する．
方法
本研究では，文芸的プログラミングのようにドキュメントの記述中にコード片を埋め込むことで，Web
Componentsのソースコードとドキュメントを同時生成する手法を提案する．ソースコードは，埋め込まれた
コード片を，ドキュメントの記述から分かる情報と組み合わせることで生成する．ドキュメントの記述が一定
の形式に従うようにすることで，フォーマットが記述内容に依存しないドキュメントが生成可能など，ドキュ
メントコメントによるドキュメント記述と同様の利点を得られるようにする．また，近年のWeb開発を鑑み
て，効率化のために記述中にテストコードや外部ツール実行のための設定を含めることを可能にする．
結論
提案手法による記述からソースコードとドキュメントを同時生成するシステムを作成し，実際に提案手法に
よる記述を行った．これと，対外発表を通して行った議論から，提案手法の特徴や改善点などを考察する．
2
目次
第 1章 序論 7
1.1 背景 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2 現状の問題 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3 目的 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4 本論文の構成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
第 2章 Web Components 9
2.1 概要 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2 コード例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3 構成する仕様群 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.1 Custom Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.2 HTML Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.3 Shadow DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
第 3章 ドキュメント生成の手法 13
3.1 概要 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2 ドキュメントコメントを用いた手法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.3 文芸的プログラミング . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
第 4章 提案手法 17
4.1 着眼点と設計 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2 ドキュメント記法の選択 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.3 Markdown記法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
第 5章 書式 21
5.1 概要 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2 マークアップ構造の記述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.3 スタイル定義の記述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.4 プロパティ定義 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.5 メソッド定義 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.6 ライフサイクルコールバック . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.7 テストコードの記述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
目次 3
5.8 デモコードの記述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.9 メタ情報の記述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.10 その他の記述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
第 6章 実装 32
6.1 概要 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.2 開発環境 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.3 処理の流れ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.4 抽象構文木の作成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.5 Polymerの使用に基づく記法の拡張 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.6 出力の生成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.6.1 ソースコードの出力 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.6.2 ドキュメントの出力 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.6.3 ReadMeの出力 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.6.4 テストコードの出力 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.7 外部ツール連携 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
第 7章 考察 42
7.1 概要 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
7.2 提案手法による記述性 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
7.3 実使用から得られた改善点 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
7.4 ドキュメントの多言語化 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
7.5 エディタの提案手法への対応 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
7.6 変換システムの動作について . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
第 8章 関連研究 47
8.1 ドキュメント生成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
8.2 コンポーネント化技術 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
8.3 Markdown記法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
第 9章 結論 51
9.1 まとめ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
9.2 今後の課題 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
9.2.1 定性的，定量的な分析 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
9.2.2 記法の改善 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
9.2.3 システムの改良・関連ツールの実装 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
参考文献 54
4
図目次
2.1 Web Componentsの定義コードの概形 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2 JavaScriptライブラリによるコンポーネントの使用例 . . . . . . . . . . . . . . . . . . . . . . 11
2.3 Web Componentsによるコンポーネントの使用例 . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.4 DOMインスタンスのメソッド呼び出し例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.5 HTML Importによる linkタグでの HTML読み込み . . . . . . . . . . . . . . . . . . . . . . 12
3.1 Javaにおけるドキュメントコメントを用いたドキュメントとソースコードの同時生成例 . . . 14
3.2 図 3.1から生成されたドキュメント . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3 文芸的プログラミングにおけるソースコードとドキュメントの生成 . . . . . . . . . . . . . . . 16
4.1 提案手法によるソースコードとドキュメントの生成 . . . . . . . . . . . . . . . . . . . . . . . 18
4.2 Markdown記法の例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.3 図 4.2より生成される HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.4 図 4.3のレンダリング結果の一例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.1 提案手法によるWeb Componentsの記述の概形 . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2 Web Componentsのコードの具体例（一部省略） . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.3 図 5.2のWeb Componentsの表示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.4 マークアップ構造の一般的定義 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.5 図 5.2に対応するマークアップ構造定義の具体例 . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.6 スタイル定義の一般的定義 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.7 図 5.2に対応するスタイル定義の具体例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.8 プロパティの一般的定義 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.9 図 5.2に対応するプロパティ定義の具体例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.10 メソッドの一般的定義 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.11 図 5.2に対応するメソッド定義の具体例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.12 ライフサイクルコールバックの一般的定義 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.13 図 5.2に対応するライフサイクルコールバック定義の具体例 . . . . . . . . . . . . . . . . . . . 28
5.14 テストコードの記述方法 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.15 テストコードの記述方法 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.16 デモコードの一般的定義 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.17 図 5.16より生成するデモコード . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
図目次 5
5.18 Front Matterの記述例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.1 Pandocから得られる JSON形式の抽象構文木の例（一部省略） . . . . . . . . . . . . . . . . . 34
6.2 Mustacheで使用するひな形の例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.3 図 6.2に適用するデータ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.4 図 6.2に図 6.3を適用することで得られるテキスト . . . . . . . . . . . . . . . . . . . . . . . . 36
6.5 提案手法により生成されるドキュメント . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.6 生成する ReadMeの例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.7 生成するテストコードの例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.8 外部ツール実行のための Front Matter部の記述例 . . . . . . . . . . . . . . . . . . . . . . . . . 40
6.9 外部ツール実行のためのシステム設定ファイル . . . . . . . . . . . . . . . . . . . . . . . . . . 40
6.10 代替言語使用のためのシステム設定ファイル . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
6.11 コード片の記述に代替言語を用いる例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.1 提案手法により記述が煩雑になってしまうWeb Componentsの定義例（API定義部のみ） . . 44
7.2 図 7.1の提案手法での記述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
7.3 テキストエディタ AtomにおけるMarkdown記法のシンタックスハイライトの例 . . . . . . . 46
8.1 ComTestによるテストコードの記述例（文献 [9]より引用） . . . . . . . . . . . . . . . . . . 47
8.2 CTSの例（文献 [3]より引用） . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
8.3 Madokoにおける文書作成の様子 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
8.4 API Blueprintにおける最も簡単なWeb APIの定義例 . . . . . . . . . . . . . . . . . . . . . . 50
8.5 図 8.4より生成されるWeb APIを定義する JSON . . . . . . . . . . . . . . . . . . . . . . . . 50
6
表目次
5.1 プロパティ定義における定義リスト記法で指定可能な内容 . . . . . . . . . . . . . . . . . . . . 25
5.2 メソッド定義における定義リスト記法で指定可能な内容 . . . . . . . . . . . . . . . . . . . . . 26
5.3 ライフサイクルコールバックの種類 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.1 プロパティに関する記述可能な Polymerの機能 . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.2 メソッドに関する記述可能な Polymerの機能 . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
7
第 1章 序論
1.1 背景
HTML5が一般的に使われるようになって以来，Webを取り巻く環境は急速に発展し，かつ大きく変化して
きた．Web ブラウザが提供もしくはサポートする機能が増強されることによってより洗練されたデザインの
Webページの公開が可能となり，動画や音声の再生などの外部プログラムを利用を前提としていた処理もWeb
ブラウザ単体で行えるようになった．また，スマートフォンやタブレットの普及に伴う閲覧デバイスと OSの
多様化によって，WebアプリケーションというWebブラウザから利用するソフトウェアも多く開発されるよ
うになった．
このような発展に従って，Web における開発手法もまた効率的になるべく変化してきた．リッチなコン
テンツやアプリケーションが増えるに従って複雑化かつ大規模化する開発に対処すべく，既存の CSS や
JavaScriptに代わり，これらで記述されたコードを生成するための代替言語とその処理系が広く普及するよう
になった．CSSの代替言語としては LESS*1や Sass/SCSS*2，JavaScriptの代替言語としては CoffeeScript*3や
TypeScript*4がよく知られている．JavaScript自体も 2015年にその標準仕様である ECMAScriptの最新仕様が
公開された*5．また，Grunt*6や Gulp.js*7などのタスクランナーと呼ばれる，代替言語の変換処理（トランスパ
イル）をはじめ Lint（文法やコーディングスタイルのチェック）や最適化などの複数のツールを用いて順に行
う処理を自動的に行うためのツールが用いられるようになった．
これら以外にも，従来のソフトウェア開発において培われてきた技法も，Web開発で用いられるようになっ
た．データとそれを表示させるUIとの橋渡しを行うための技術であるデータバインディングや，Angular.js*8や
Vue.js*9などのフレームワークが採用しているMVVM（Model/View/ViewModel）モデルなどがそれに当たる．
そのような技術の 1つとしてコンポーネント化がある．ある要素を部品として定義し，それを容易に再利用す
るための技術である．CGIを除けば，従来 JavaScriptライブラリによってそれを実現してきたが，新たにWeb
Componentsという仕様が現れた．現状，仕様策定段階にあるため広く使える技術とは言えないものの，今後
は一般的に普及していくと考えられる．
*1 http://lesscss.org/
*2 http://sass-lang.com/
*3 http://coffeescript.org/
*4 http://www.typescriptlang.org/
*5 http://www.ecma-international.org/publications/standards/Ecma-262.htm
*6 http://gruntjs.com/
*7 http://gulpjs.com/
*8 https://angularjs.org/
*9 http://jp.vuejs.org/
第 1章 序論 8
1.2 現状の問題
コンポーネント化する作業において，作成後の使用のためにコンポーネントに関する API一覧やその使用方
法等をまとめたドキュメント（以下，断りがなければ「解説文書」としての意味で用いる）を作成することは
重要である．従来のソフトウェア開発では，このドキュメントの作成の手間を削減すべく，ソースコードと同
時にドキュメントを作成する手法を用いてきた．しかしながら，従来の手法をWeb Componentsに適用するこ
とは難しく，ドキュメントを個別に作成するかソースコード中に含まれるコメントそのものをドキュメントと
して扱うことが一般的となっている．
1.3 目的
本研究では，従来の手法をもとに 1つの記述から 1つのソースコードとドキュメントの対を生成する，Web
Components開発のための手法を提案する．そして，提案手法を用いた開発を行うためのツールを実際に作成
し，この手法について議論する．
1.4 本論文の構成
論文の構成を簡単に説明する．本章では，序論として研究の背景と問題点，目的について述べた．第 2章
では，本研究が対象とするWeb Componentsについて述べる．第 3章では，従来用いられてきたソースコード
とドキュメントの同時生成手法について述べる．第 4章では，本研究の提案する生成手法について述べる．第
5 章では，本研究で提案するWeb Components の記述方法について述べる．第 6 章では， ソースコードとド
キュメントを生成するシステムの実装について述べる．第 7章では，提案手法に関する考察について述べる．
第 8章では，本研究に関連する研究について述べる．第 9章では，結論と今後の課題について述べる．
9
第 2章 Web Components
2.1 概要
Web Components*1は，Web ページ中の構成要素をコンポーネント化して，再利用するための技術である．
具体的には，ボタンなどのユーザインタフェースを構成するマークアップと，それに対するスタイル定義と動
作スクリプトをまとめるものである．Web Componentsは複数の仕様から構成されているが，いずれもW3C*2
のWorking Draftとして策定が進められている．
現在仕様策定中の技術であるため，利用可能なブラウザや実際に採用しているWebサイトは少ない．しか
しながら，Google の Chrome ブラウザ*3はWeb Components の多くの機能を利用することが可能であり，モ
ダンなブラウザであれば webcomponents.js*4 などの Polyfill を用いることで Chrome ブラウザと同等に Web
Componentsを使用することができる．また，CustomElements.io*5によれば，2016年 1月 14日現在 1500を
超すコンポーネントが公開されて利用可能な状態にある．
2.2 コード例
Web Components の定義を行う（と同時にその実体である）コードの概形を図 2.1 に示す．図 2.1 の通り，
Web Componentsは HTMLファイルとして提供される．
図 2.1の HTMLファイルは，コンポーネント化する部分に対応するマークアップ（9行目から 11行目）と
それに対するスタイルを定義する CSS（3行目から 7行目），そしてコンポーネントの動作および APIを定義
する JavaScript（13行目から 35行目）から構成されている．
2.3 構成する仕様群
Web Componentsは 3つの仕様から構成されている．以下では，Web Componentsを構成する各仕様につい
て述べていく．
*1 http://webcomponents.org/
*2 World Wide Web Consortiumの略．https://www.w3.org/*3 https://www.google.co.jp/chrome/
*4 https://github.com/webcomponents/webcomponentsjs
*5 https://customelements.io/
第 2章 Web Components 10
� �1 <!-- markup definition -->2 <template>3 <style>4 /* styling */5 #hoge { background: yellow; }6 p {font-weight: bold; font-size: 16px;}7 </style>8 <!-- markup -->9 <div id=’hoge’>
10 <p>Hello, world.</p>11 </div>12 </template>13 <script>14 //define components15 (function() {16 //define methods or properties17 var proto = Object.create(HTMLElement.prototype);18 proto.methodName = function(...){...};19 proto.propName = ...;2021 //Shadow DOM create22 var doc = document.currentScript.ownerDocment;23 proto.createCallback = function() {24 var tmpl = doc.querySelector("template");25 var tmplCode = doc.importNode(tmpl.content, true);26 var sroot = this.createShadowRoot();27 sroot.appendChild(tmplCode);28 ...29 }30 ...3132 //register element33 var Tag = document.registerElement(’tag-name’, {prototype: proto});34 })();35 </script>� �
図 2.1: Web Componentsの定義コードの概形
2.3.1 Custom Elements
Custom Elements*6は，ユーザが独自に新たなタグを定義して使用するための機能を提供する．
従来の JavaScriptライブラリによるコンポーネント化においては，divなどの汎用的に用いられている通常
のタグを用いて，コンポーネントの展開先を記述しなければならない．その際には，クラス属性にコンポーネ
ントの展開先を示す内容（例えばコンポーネント名など）を追加し，コンポーネントの展開先としての用途と
それ以外の用途で区別する必要がある．さらに，コンポーネントを使用するための前処理として，これらの展
開先を指定しライブラリごとに異なる初期化関数を呼び出す必要がある (図 2.2）．
そこで，Custom Elementsの機能を用いることで，コンポーネントそれ自体を表すためのタグを定義してそ
れを使用することが可能になる．同時に，ユーザが明示的に初期化関数を呼び出す必要もなくなるため，コン
ポーネントの使用がより簡易で統一的なものとなる（図 2.3）．
図 2.1の 33行目では，document.registerElementという APIを呼び出すことで，独自タグの登録を行っ
ている．この API の第 1 引数には作成する独自タグの名前を指定する．指定する名前には数字からはじめな
い，ハイフン（-）を 1つ以上入れる，という制限が設けられている．これは，現在標準的に用意されている
タグや，今後標準的に用意されるタグとの競合を防ぐためである．第 2 引数には，ユーザが JavaScript から
コンポーネント化した要素を扱うにあたり，提供する API を格納したオブジェクトを指定する．これによっ
て，コンポーネントが提供する操作や状態を DOM インスタンスのメソッド・プロパティとしてアクセスす
ることが可能になる．なお，各タグを表す DOMインスタンスのフィールド値のうち，型が関数（Function）
*6 http://www.w3.org/TR/custom-elements/
第 2章 Web Components 11
� �<!-- コンポーネントの展開先 --><div class="component-wrapper">...
</div>...<script>// コンポーネントの展開先となる要素を取得var destination = document.querySelectorAll(".component-wrapper");
// J a v a S c r i p tライブラリの仕様に合わせて、コンポーネントを展開するfor (var i = 0; i < destination.length; ++i) {HogeFuga.init(destination[i]);
}
...</script>� �
図 2.2: JavaScriptライブラリによるコンポーネントの使用例
� �<!-- コンポーネントの展開先であり，かつコンポーネント自体でもある --><hoge-fuga>...
</hoge-fuga>� �図 2.3: Web Componentsによるコンポーネントの使用例
� �...<audio id="foo" src="hoge.wav"></audio>...<script>var player = document.querySelector("#foo");// hoge. w a vを再生するplayer.play();</script>� �
図 2.4: DOMインスタンスのメソッド呼び出し例
であるものをメソッド，それ以外をプロパティと呼ぶ．例えば，HTML5には，音声を再生するために用いる
audioタグが用意されている．JavaScriptからこのタグの DOMインスタンスを取得し，playというメソッド
を呼び出すと，src属性（プロパティでもある）に指定した音声ファイルを再生することができる（図 2.4）．
document.registerElementの第 2引数は独自タグに対し，DOMインスタンスを通じてこのような操作を
行うためのプロパティやメソッドを設定するために用いる．
また，図 2.2 に見られるコンポーネントの展開処理は，図 2.1 の 23 行目から 29 行目で定義してい
る createdCallback という特殊なメソッドにその処理内容を記述し，document.registerElement の第
二引数に渡すオブジェクトに含めることで独自タグの使用に際して自動的に行われるようにしている．
createdCallbackなどの特殊なメソッドについては，後ほど 5.6節で詳しく扱う．
第 2章 Web Components 12
� �<link rel="import" href="path/to/components.html" />� �
図 2.5: HTML Importによる linkタグでの HTML読み込み
2.3.2 HTML Import
HTML Import*7は，linkタグを用いて HTMLファイル，つまりWeb Componentsを読み込むための仕様で
ある．図 2.5のような linkタグの記述をすることで，HTMLファイルを読み込むことができる．
従来の JavaScriptライブラリによるコンポーネント化においては，JavaScriptライブラリとマークアップに
対するデザインを定義する CSSそれぞれについて読み込むための記述をする必要があるが，この仕様によっ
て必要なリソースをまとめた HTMLを 1つ読み込む記述に変更することができる．
HTML中に JavaScriptを記述するのとは異なり，JavaScript中に HTMLを記述したい場合，文字列として
保持する必要がある．JavaScriptライブラリによるコンポーネント化においても，コンポーネント部分のマー
クアップ構造を表す HTMLを文字列として保持する必要がある．しかし，JavaScriptの文字列は改行を「\n」
というエスケープシーケンスとして表現する必要があり，改行として表現したまま文字列にすることができな
い*8．そのため，マークアップ構造は一行の長い文字列として保持する必要があり，その修正や更新に手間が
かかっていた．HTML Importにより，HTMLファイルをそのまま読み込んで用いることができるため，この
ようなマークアップ構造を扱う手間を削減することができている．
2.3.3 Shadow DOM
Shadow DOM*9はマークアップ構造とそれに対するスタイルをカプセル化する仕様である．
従来の JavaScriptライブラリによるコンポーネント化をはじめ，id属性や class属性に値を設定すること
でスタイル定義を適用するなどの操作の対象を指定する場合，その値（図 2.2の場合，component-wrapper）
が競合しないように注意する必要がある．これらの値が競合している場合，コンポーネントの使用によって，
デザイン崩れや予期せぬ動作を引き起こしてしまう場合がある．このような問題を避けるべく，コンポーネン
ト化部分に対する class属性値を<library name>-wrapperのような値にするなど，コンポーネントの開発
者は class属性値などが競合しないよう注意する必要がある．しかし，このような対処は本質的な解決にはな
らず，ユーザ側もコンポーネントで用いている class属性値と競合するような値を使用しないように注意する
必要がある．
Shadow DOMでは，マークアップ構造をカプセル化することで，このような値の競合に注意せずとも正常に
動作することを可能にする．また，ユーザからは直接コンポーネント化部分のマークアップ構造とそれに対す
るスタイル指定にアクセスができなくなるため，より適した形でのコンポーネントの提供が可能になる．
図 2.1では，26行目と 27行目においてカプセル化が行われている．26行目の createShadowRootメソッ
ドの呼び出しによって，Shadow DOMインスタンスを生成する．生成した Shadow DOMインスタンスにマー
クアップ構造を追加する（27行目）ことで，カプセル化を実現する．
*7 http://www.w3.org/TR/html-imports/
*8 ECMAScript2015において，改行を改行として表現可能な文字列リテラルが追加されている．*9 http://www.w3.org/TR/shadow-dom/
13
第 3章 ドキュメント生成の手法
3.1 概要
第 1章では，解決すべき問題点として，Web Componentsにおけるソースコードとドキュメントを同時に生
成するために従来の手法が使えないことを指摘した．以下では，その手法について代表的なものを 2つ挙げ，
それらの特徴とWeb Componentsに適用できない理由について述べていく．
3.2 ドキュメントコメントを用いた手法
Javaにおける JavaDoc*1というツールは，ソースコード中に含まれる/**と*/で囲まれたコメント内に記述
された内容（例を図 3.1に示す）とソースコードの内容からドキュメント（例を図 3.2に示す）を生成する．こ
のように，ソースコード中の特殊なコメント（ドキュメントコメント）によって記述された内容を解析し，ド
キュメントを生成する方法を，ここではドキュメントコメントを用いた手法と呼ぶ．
ドキュメントコメントを用いてドキュメントを生成する手法は，さまざまなプログラミング言語において現
在広く使われている手法である．JavaDocをはじめ C/C++や PHP，Fortranなどの多くの言語に対応している
Doxygen*2 や JavaScript向けの JSDoc*3などのツールが代表的である．
この手法を用いる利点として，主に 2つを挙げることができる．1つは，ドキュメントの記述方法がある程
度形式化されている，という点である．図 3.1 のドキュメントコメントの例を見ると，引数に関する記述は
「@param 引数名 説明」の形で記述され，戻り値に関する記述は「@return 戻り値の説明」の形で記述され
ている．このように，記述の形が定められることで，ドキュメントの書式を書き手によらずにある程度統一
することができる．また，ソースコード自体を読む際にも，コメントとしての可読性を向上できる．加えて，
Eclipse*4などの IDEではドキュメントコメントの自動生成を行うことができるが，これもドキュメントの記述
形式が定まっているからこそ提供できる機能である．もう 1つは，ドキュメントとして書式が整ったものが生
成可能である，という点である．引数に関する説明，戻り値に関する説明などをそれぞれ抽出して，適した形
式でそれらの説明を見せるように出力することで生成ドキュメントの質を上げている．これは，記述形式を形
式化することで可能となっている．
Web Componentsに着目した場合，残念ながらこのドキュメントコメントを用いた手法を適用してドキュメ
ント生成を行うことは難しいと考えられる．それは，対象とするソースコードが単一のプログラミング言語で
記述されていないためである．
*1 http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html
*2 http://www.doxygen.org/
*3 http://usejsdoc.org/
*4 https://eclipse.org/
第 3章 ドキュメント生成の手法 14
� �1 /**2 * 四則演算を行うクラス3 *4 * @author 海老澤雄太5 * @version 0.0.16 */7 public class Arithmetic {8 /**9 * 足し算を行う
10 *11 * @param augend 被加数12 * @param addend 加数13 * @return 2つの引数の加算結果14 */15 public int add(int augend, int addend) {16 return augend + addend;17 }18 }� �
図 3.1: Javaにおけるドキュメントコメントを用いたドキュメントとソースコードの同時生成例
Web Components の場合，HTML 形式で提供されているが API はその中の script タグの中に記述された
JavaScriptによって定義されている．Cや Javaなどの場合は，それぞれの言語のパーサを用いてコメント部分
を抽出すれば良いが，Web Componentsではそうはいかない．HTMLと JavaScriptのパーサを組み合わせるこ
とで，JavaScript部分に含まれるコメントを抽出できるが，他の言語を対象とする場合と比較して実装の複雑
が増してしまう．
また，Web Components は JavaScript からのみ扱う対象ではなく，定義した独自タグを HTML 中に記述
して使用するものである．この点を考慮すると，API を定義する JavaScript 中のドキュメントコメントとし
て HTML タグとして使用する場合の使用例などを記述するのは不自然であると考えられる．同様に，Web
Components の著者情報やライセンス情報などをソースコードの先頭部分以外に記述するのも不自然である．
このように，Web Componentsのドキュメント情報には，それぞれに記述すべき位置というものが考えられる．
そのため，複数のプログラミング言語におけるドキュメントコメントの記述方法を策定し，複数のパーサでそ
れぞれのコメント部分からドキュメントコメントを抽出しなければこの問題を解決することはできない．これ
はシステムを複雑にするばかりか，ドキュメントコメントの書き手とソースコードの読み手を不必要に混乱さ
せてしまう原因となりうる．
以上のことから，Web Componentsにおいてドキュメントコメントを用いた手法を適用することは難しい．
3.3 文芸的プログラミング
Knuthが提唱する文芸的プログラミング [6]は，ドキュメントコメントを用いた手法とは別の，ソースコー
ドとドキュメントを生成するための手法である．文芸的プログラミングでは，コードの断片をドキュメントの
記述の中に埋め込み，それをドキュメントと対応付けを行うことでドキュメントを生成する．
文芸的プログラミングでは，コード片とドキュメント記述が合わさった文書を対象に tangleというツールを
用いてソースコードを生成し，weaveというツールを用いてドキュメントソースを生成する（図 3.3）．これら
のツールの生成物をそれぞれの処理系を用いることで完成したプログラムとドキュメントが得られるように設
計されている．
ドキュメント記述内にコード片を埋め込む手法のため，ドキュメントコメントを用いた手法と比較してWeb
Componentsに対しても不都合なくドキュメントを記述することが可能である．しかしながら，文芸的プログ
ラミングではドキュメント記述に対する自由度が高い一方で，ドキュメントコメントのような形式化がされて
第 3章 ドキュメント生成の手法 15
図 3.2: 図 3.1から生成されたドキュメント
第 3章 ドキュメント生成の手法 16
図 3.3: 文芸的プログラミングにおけるソースコードとドキュメントの生成
いないため，記述の仕方が書き手に依存するという問題がある．また，文芸的プログラミングにおいて出力さ
れるドキュメントは概して，コード片を参照しながらその実装理由などを説明することに特化しており，API
ドキュメントなどのエンドユーザ向けのドキュメント生成に向いていない．
17
第 4章 提案手法
4.1 着眼点と設計
第 3章では，ソースコードとドキュメントを同時に生成するための既存の手法について述べ，Web Components
に対してそのままでは適用できないことを述べた．ここで，各手法の問題点をまとめると，ドキュメントコメ
ントを用いる手法ではコメントを記述するという点で不都合な状況があるということ，文芸的プログラミング
ではドキュメントの記述内容や生成フォーマットに難があるということだった．
そこで，本研究ではそれぞれの既存手法に着目し，両者の性質を組み合わせることで，Web Componentsと
いう対象に対しそれぞれの欠点を解決する．
具体的には，文芸的プログラミングのように，ドキュメントの記述中にコード片を埋め込むことでソース
コードとドキュメントの同時生成を行う．それにあたり，ドキュメントの記述に対し一定の形式化や制限を加
えることで，ドキュメントコメントを用いる手法のように記述の統一や整ったドキュメント生成を可能にする．
提案手法によるソースコードとドキュメントの生成処理の概念図を，図 4.1に示す．入力となるファイルに
は，ドキュメントの記述の中に，マークアップを表す HTMLや APIを定義する JavaScriptなどのコード片が
埋め込まれている．システムは，このドキュメントを解析し，埋め込まれたコード片とドキュメントの記述内
容から分かるコードの構造から，完成したWeb Componentsのソースコードを生成する．そして，コード片を
取り除きドキュメント記述を一定の形式に整形することで，書式の整ったドキュメントを生成する．
また，第 1章で述べたように，近年のWeb開発ではソースコードのスタイルチェックや最適化など，さまざ
まなツールを使用することが想定される．そこで，処理系が生成したソースコードに対し，自動的にこれらの
ツールを適用できるよう，そのための記述についても考慮する．
4.2 ドキュメント記法の選択
提案手法として文芸的プログラミングのスタイルを適用する上で，ドキュメントをどのような記法を用いて
記述するかを考えなければならない．Knuthの提唱したシステムでは，ドキュメント記法として TEXが採用
されていたが，文芸的プログラミングにおいては用いるドキュメント記法を定めてはいない [6]．
ドキュメント記法には TEX以外にも，文献 [6]で挙げられている Scribeや troff，XMLや reStructuredText*1と
いうように多くのものが存在している．それらの中から，適当なものを採用することは，提案手法の利便性を
考える上でとても重要である．
提案手法に用いるドキュメント記法を考える際，それが満たすべき条件が 4つ考えられる．まず 1つ目に記
述が容易な記法であること，2つ目に人間にとって読みやすい記法であることが挙げられる．これは，提案手
*1 http://docutils.sourceforge.net/rst.html
第 4章 提案手法 18
図 4.1: 提案手法によるソースコードとドキュメントの生成
法を用いて開発を行う上で最も重要な指標となる．記述にコストがかかる記法，文書構造の把握が難しい記法
では，ドキュメントを同時に作る以前の問題として，開発効率を下げてしまうためである．3つ目の条件はド
キュメントを記述する上で最低限必要な文書構造を記述可能なことである．この条件を満たすことで，ドキュ
メントコメントを用いる手法と同様に，形式化した記述が可能になると考えた．また，最低限必要な文書構造
としては見出しやリスト構造などのほかに，プログラムコードを提示するための構造があることを求めてい
る．4つ目の条件は，すでに広く知られており，多くの場面で活用されている記法であることとした．提案手
法のための新たなドキュメント記法を設計することや，既存の記法に何かしらの拡張を加えることも考えられ
たが，その場合は提案手法を用いるための学習コストが大きくなってしまう．そこで，提案手法を用いるため
に必要な学習コストを低く抑えることを目的に，これら 3つ目と 4つ目の条件を設けている．
本研究では，これらの条件を満たす記法として，Markdown記法*2を採用した．次の節では，この記法につ
いての説明と採用理由について述べる．
4.3 Markdown記法
Markdown記法は，Gruberが提唱する，HTMLへの変換を主な目的とする簡易マークアップ言語である．現
在，CommonMarkの名称で，標準化に向けた仕様策定と議論が行われている*3．Markdown記法の例を図 4.2
に示す．また，これを HTMLへと変換した結果を図 4.3に，図 4.3の HTMLをWebブラウザにて表示した結
果を図 4.4に示す．
Markdown記法は図 4.2のように，テキストメールの装飾に似たシンプルな方法で文書構造を表す．XMLの
ようにタグを用いたり，TEXの「\section{見出し名}」のようにコマンドやマクロを必要としないため，非常
に記述が簡単である．記法の読みやすさに関しても，テキストメールなどで使われる意味とほぼ同義であるこ
ととタグやコマンドを用いないことから，プレーンテキストの状態でも十分に読みやすさが確保されている．
図 4.2と図 4.3を見ると，Markdown記法によって「見出し」「段落」「引用」「リスト」「プログラムコード
*2 https://daringfireball.net/projects/markdown/
*3 http://commonmark.org/
第 4章 提案手法 19
� �1 # レベル1の見出し2 ## レベル2の見出し3 ### レベル3の見出し45 レベル1の見出しの別の記述例6 ======================78 レベル2の見出しの別の記述例9 ----------------------
1011 空行から空行までの間が1つの段落として表現される。12 テキストについては *斜体* もしくは **強調** の装飾が可能。1314 > 引用を表す記法は15 > メールでのやり方によく似ている1617 [アンカーテキスト]( http://www.example.com)と U R Lを指定して、18 リンクを表現することができる。1920 - リスト構造も21 - 入れ子で22 - 記述が可能2324 ‘‘‘javascript25 // プログラムコードの埋め込み例26 console.log("Hello, world.");27 ‘‘‘� �
図 4.2: Markdown記法の例
（コードブロック）」など，さまざまな文書構造を記述できることが見て取れる．このことから，提案手法に用
いる上で十分な文書構造を分かりやすく記述することが可能であることが分かる．
Markdown 記法は，現在 Web を中心に，非常に多くの場面で活用されている．例えば，git ホスティング
サービスの 1つである GitHub*4は，プロジェクトの ReadMeをはじめコメントや問題報告などに Markdown
記法を用いることができる．また，ブログシステムあるいは CMS（Contents Management System）である
WordPress*5 やブログサービスの 1つである「はてなブログ」*6では，ブログ記事の執筆にMarkdown記法を用
いることができる．このように，Markdown記法は広く知られ，多くの場面に活用されている記法である．
以上のことから，Markdown記法は提案手法に用いる記法が満たすべき条件をすべて満たしていることが分
かる．よって，本研究では提案手法に用いるドキュメント記法として，Markdown記法を採用した．
*4 https://github.com/
*5 https://wordpress.org/
*6 http://hatenablog.com/
第 4章 提案手法 20
� �1 <h1>レベル1の見出し </h1>2 <h2>レベル2の見出し </h2>3 <h3>レベル3の見出し </h3>45 <h1>レベル1の見出しの別の記述例 </h1>6 <h2>レベル2の見出しの別の記述例 </h2>78 <p>空行から空行までの間が1つの段落として表現される。 テキストについては <em>斜体</em> もしくは <strong>強
調</strong> の装飾が可能。 </p>9
10 <blockquote>11 <p>引用を表す記法は メールでのやり方によく似ている </p>12 </blockquote>1314 <p><a href="http://www.example.com">アンカーテキスト</a>と U R Lを指定して、 リンクを表現することができる。 </p>1516 <ul>17 <li>リスト構造も18 <ul>19 <li>入れ子で20 <ul>21 <li>記述が可能</li>22 </ul></li>23 </ul></li>24 </ul>25 <pre class="sourceCode javascript"><code class="sourceCode javascript"><span class="co">// プログラムコード
の埋め込み例 </span>26 <span class="ot">console</span>.<span class="fu">log</span>(<span class="st">"Hello, world."</span
>);</code></pre>� �図 4.3: 図 4.2より生成される HTML
図 4.4: 図 4.3のレンダリング結果の一例
21
第 5章 書式
5.1 概要
以下では，提案手法による Web Components の記述方法について述べていく．提案手法における Web
Componentsの記述は次に示す図 5.1のように行う．
Markdown記法による記述は，まずレベル 1の見出しで始める．提案手法では，文書のはじめのレベル 1の
見出しを，作成するWeb Componentsのタグ名として扱う．そのため，数字からはじまる，ハイフン（-）が
含まれないなど，Custom Elementsの仕様に反する場合はこれをエラーとする．
レベル 1の見出しの後の内容は，レベル 2の見出しから次のレベル 2の見出しまでの内容を 1単位として，
内容を解析していく．あるレベルの見出しから，次に現れるそれ以上のレベルの見出しまでの内容の単位を以
後セクションとよび，セクションの開始の見出しレベルに応じて「レベル nのセクション」，見出しの内容に
応じて「SectionTitleセクション」などと呼称する．例えば図 5.1の 3行目と 4行目の場合，「レベル 2のセク
ション」や「descriptionセクション」と表す．
次の節からは，Web Componentsの構造をどのようなセクションで記述するか，セクション内でどのように
記述するかについて説明する．なお，提案手法における記述方法の理解を助けるため，一般的な定義を示すほ
かに，図 5.2のWeb Componentsのコードを出力するための記述の具体例（完全なコードは付録 Aを参照）に
ついても述べる．このWeb Componentsは簡単なカウンター UIであり，クリックすることで数値を増やすこ
とができる（図 5.3）．また，JavaScriptから操作することでカウンターの値を増減することや，クリック時に
動作させる関数の登録を行えるようになっている．このコードでは，現在Web Componentsを作成する上で多
く使われているラッパーライブラリ，Polymer*1を使用して定義している．
� �1 # component-name23 ## description4 explanation of this component.56 ## properties7 definitions of properties.8 ...9
10 ## methods11 definitions of properties.12 ...1314 ## others15 ...� �
図 5.1: 提案手法によるWeb Componentsの記述の概形
*1 https://www.polymer-project.org/1.0/
第 5章 書式 22
� �1 <link rel="import" href="bower_components/polymer/polymer.html" />23 <dom-module id="my-counter">4 <template>5 <style>6 #container {7 display: inline-block;8 font-size: 16px;9 line-height: 20px;
10 height: 20px;11 padding: 0 4px;12 font-family: sans-serif;13 color: #223;14 background-color: #4CCFFF;15 border: 1px solid #0084B4;16 border-radius: 2px;17 cursor: pointer;18 }1920 /* 省略 */2122 </style>2324 <div id="container">25 <div id="heart"></div>26 <div id="count">27 Value: <span id="num">0</span>28 </div>29 </div>30 </template>3132 <script>33 (function(){34 Polymer({35 is: "my-counter",3637 properties: {38 count: {39 type: Number,40 value: 041 },42 },4344 _callback: undefined ,4546 set: function(value) {47 if (!value || typeof value !== "number") {48 return this.value;49 }5051 this.count = Math.round(value);52 this.$.num.textContent = this.count;5354 return this.count;55 },5657 increase: function(value) {58 if (!value || typeof value !== "number") {59 value = 1;60 }6162 this.count += Math.round(value);63 this.$.num.textContent = this.count;6465 return this.count;66 },6768 // 省略6970 attached: function() {71 this.$.container.addEventListener(72 "click", this._clickHandler.bind(this));7374 if (typeof this.count !== "number") {75 this.count = 0;76 }77 else {78 this.$.num.textContent = this.count;79 }80 }81 });82 })();83 </script>84 </dom-module>� �
図 5.2: Web Componentsのコードの具体例（一部省略）
第 5章 書式 23
図 5.3: 図 5.2のWeb Componentsの表示例
� �## structureマークアップ構造に関する説明
‘‘‘html<div class=’box’><p></p>
</div>‘‘‘� �
図 5.4: マークアップ構造の一般的定義
� �3 ## structure45 ‘‘‘html6 <div id="container">7 <div id="heart"></div>8 <div id="count">9 <span id="num"></span> LIKE
10 </div>11 </div>12 ‘‘‘� �
図 5.5: 図 5.2に対応するマークアップ構造定義の具体例
5.2 マークアップ構造の記述
コンポーネント化する部分に対応するマークアップ構造の記述は，structureセクションで定義を行う．
structureセクション内に最初に現れるコードブロックの内容を抽出し，それをコンポーネントのマークアッ
プ構造のコードとして使用する．一般的な定義と，図 5.2に対応する定義例をそれぞれ図 5.4，図 5.5に示す．
セクション内に最初に現れるコードブロックがマークアップ構造として用いられるということを除けば，そ
れ以外はセクション内の記述はほぼ自由に行うことができる．ただし，マークアップの構造に関する説明は実
装を確認したい場合やそれに手を加えたい場合にのみ必要であり，コンポーネントを使用する上では不要と考
えられる．そのため，コード片以外の情報は，ソースコード生成およびドキュメント生成には使用しない．
5.3 スタイル定義の記述
コンポーネントに適用するスタイル定義は，styleセクション内で行う．
マークアップ構造の定義と同様，セクション内に最初に現れるコードブロックの内容を抽出し，ソースコー
ド生成に使用する．その他の内容をソースコード生成およびドキュメント生成に使用しないのもマークアップ
構造の定義と同様である．
一般的な定義と，図 5.2に対応する定義例をそれぞれ図 5.6，図 5.7に示す．
第 5章 書式 24
� �## styleスタイル定義に関する説明
‘‘‘css.box { background: yellow; }p { font-weight: bold; font-size: 16px; }‘‘‘� �
図 5.6: スタイル定義の一般的定義
� �14 ## style1516 ‘‘‘css17 #container {18 display: inline-block;19 font-size: 16px;20 line-height: 20px;21 height: 20px;22 padding: 0 4px;23 font-family: sans-serif;24 color: #223;25 background-color: #4CCFFF;26 border: 1px solid #0084B4;27 border-radius: 2px;28 cursor: pointer;29 }3031 /* 省略 */32 ‘‘‘� �
図 5.7: 図 5.2に対応するスタイル定義の具体例
5.4 プロパティ定義
プロパティに関する定義は，propertiesセクションで行う．
マークアップ構造やスタイル定義の記述とは異なり，プロパティ定義ではプロパティごとにその詳細情報を
記述しながら定義していく．具体的には，図 5.8の一般的定義のように定義リスト記法を用いて定義を行う．
定義リストから次の定義リストまでの内容を，1 つのプロパティの定義として解釈する．定義リストでは，
用語に当たる部分にプロパティ名を，説明に当たる部分にデータの型や初期値などの情報を指定する．記述の
順序は特に指定しない．説明部分に記述可能な内容とその意味を表 5.1に示す．定義リストに続く，次の定義
リストまでの内容は，プロパティに関する説明として使用する．
定義リスト記法は，PHP Markdown Extra*2にて定義された記法であり，Gruber が提唱するオリジナルの
Markdown記法や CommonMarkには存在しない．しかしながら，ドキュメント記述の自由度と形式化を両立
させるために，敢えて拡張記法を採用してプロパティ定義を行うようにした．拡張記法を用いて記述する部分
を形式化することで，それ以外の部分をオリジナルの Markdown 記法の範疇で自由に記述できるようにして
いる．
プロパティの型の指定は「type 型名」の形式で行う．許容される型は Boolean/Number/String/Date/Ar-
ray/Objectのいずれかである．指定されない場合，もしくはこれら以外の型が指定された場合は，Stringに変
更する．これは，audioタグの src属性のように，独自タグの属性値を通じて対応するプロパティの値を設定
するという機能を提供することを考慮に入れているためである．JavaScriptから getAttributeなどの APIを
通じて得られる属性値が文字列（String）であるため，それに合わせる形で Stringをデフォルトの型指定とし
*2 https://michelf.ca/projects/php-markdown/extra/
第 5章 書式 25
� �## properties
propertyName1: ‘"initial value"‘: type String
プロパティ定義例1ここに propertyName1に関する説明を記述
propertyName2: type Number: ‘1234567890‘: private
プロパティ定義例2ここに propertyName2に関する説明を記述� �
図 5.8: プロパティの一般的定義
表 5.1: プロパティ定義における定義リスト記法で指定可能な内容
記述 意味
‘value‘ 初期値を valueに設定type 型名 型を指定private 情報をドキュメントに出力しない
� �34 ## properties3536 count37 : type Number38 : ‘0‘3940 カウンターの値。4142 _callback43 : private4445 コンポーネントクリック時に実行する関数� �
図 5.9: 図 5.2に対応するプロパティ定義の具体例
て扱う．後述する private指定がされている場合は，このチェックを実行しない．プロパティの初期値の指
定は，インラインコード記法によって直接リテラルを記述する．指定がない場合は，undefinedもしくは型指
定から初期値を決定する．private指定は，該当プロパティの情報をドキュメントに出力しないための設定で
ある．内部処理のために必要だがユーザに公開したくないプロパティを定義する際に用いる．この指定によっ
て，該当プロパティの定義リストから次の定義リストまでの範囲の内容が隠蔽される．
5.5 メソッド定義
メソッドに関する定義は，methodsセクションで行う．
メソッドに関する定義も，プロパティ同様に定義リスト記法を用いて定義を行う．プロパティ定義と異なる
点は，処理内容を記述する必要があることである．メソッド定義の一般的な定義と，図 5.2に対応する定義例
をそれぞれ図 5.10，図 5.11に示す．
メソッド定義では，定義リストの用語に当たる部分にメソッド名を，説明に当たる部分に引数や戻り値の情
報を指定する．説明部分に記述可能な内容とその意味を表 5.2に示す．定義リストに続く，次の定義リストま
第 5章 書式 26
� �## methods
methodName: param {型名} 引数1 説明: param {型名} [引数2] 説明: return {型名} 戻り値に関する説明
methodNameについての説明
‘‘‘javascript// メソッドの処理内容の定義return arg1 + (arg2 || 0);‘‘‘� �
図 5.10: メソッドの一般的定義
表 5.2: メソッド定義における定義リスト記法で指定可能な内容
記述 意味
param {型名 } 引数名 説明 メソッドの受け取る引数を設定return {型名 } 説明 メソッドの戻り値についての説明を記述private 情報をドキュメントに出力しないasync メソッドが非同期処理を行うことを示すchainable メソッドチェーン可能なメソッドであることを示すdepricated 使用が非推奨となったメソッドであることを示す
での内容には，メソッドに関する説明のほかにメソッドの処理コードの定義を行う．
メソッドの引数の指定は「param {型名 } 引数名 説明」の形式で行う．引数の型は，プロパティ定義とは異
なり，いかなる型でも許容される．省略可能な引数を表現する場合は，引数名を []で囲むことでそれを表す．
メソッドの引数の順番と，この記述の順番は一致させる．メソッドの戻り値の指定は「return {型名 } 説明」の形式で行う．private指定はプロパティ定義と同様，ドキュメントに情報を出力しないために用いる．さら
に，メソッドのいくつかの特徴を表すための指定を用意した．使用が非推奨となったことを表す depricated，
メソッドチェーン呼び出しが可能であることを表す chainable，非同期処理を行うことを表す asyncの 3種
類の指定がある．これらはソースコード生成には使用しないが，生成するドキュメントにこれらの情報が表示
されるようにする．また，無引数で戻り値もなく，他の指定も一切必要ないメソッドを定義する場合も考えら
れる．その場合は，説明部に noneなど，表に示した記述以外の内容の記述を 1つ入れることで表現する．
定義リストから定義リストまでの内容はプロパティ定義同様にメソッドの説明として扱うが，該当部分で最
後に現れるコードブロックの内容を，定義するメソッドの処理内容を表すコードとして使用する．それ以外の
コードブロックは，定義するメソッドの使用方法などを説明するためのコード片だと解釈して，ドキュメント
生成に使用する．このコードブロック記法で記述するコードには，「メソッド名: function(引数リスト) {」などの関数としての外皮に当たる部分の記述はせず，純粋に処理内容のコードだけを記述する．これは，定義
リスト記法でのメソッド情報から容易に生成することが可能なため，可能な限り不要な記述の重複を避けるこ
とを重視した結果である．もし，コードブロックが 1つも現れない場合には，何も処理をしない空のメソッド
としてコードを生成する．
第 5章 書式 27
� �47 ## methods4849 set50 : param {Number} value 新しくセットするカウンターの値51 : return {Number} 更新後のカウンターの値5253 カウンターの値を引数の数値に更新する。54 引数の数値は四捨五入によって整数値に丸められる。5556 ‘‘‘javascript57 if (!value || typeof value !== "number") {58 return this.value;59 }6061 this.count = Math.round(value);62 this.$.num.textContent = this.count;6364 return this.count;65 ‘‘‘6667 increase68 : param {Number} value カウンターの値の変化量69 : return {Number} 更新後のカウンターの値7071 カウンターの値を引数の数値分だけ増加させる。72 引数の数値は四捨五入によって整数値に丸められる。73 引数に負数を与えることで、減じることも可能。7475 ‘‘‘javascript76 if (!value || typeof value !== "number") {77 value = 1;78 }7980 this.count += Math.round(value);81 this.$.num.textContent = this.count;8283 return this.count;84 ‘‘‘� �
図 5.11: 図 5.2に対応するメソッド定義の具体例
5.6 ライフサイクルコールバック
Web Componentsには，2.3.1節で取り上げた createdCallbackなど，特定のタイミングに自動的に呼び出
されるメソッドを定義することができる．これらはライフサイクルコールバックと呼ばれ，表 5.3に示す種類
のメソッドを定義することができる．
ライフサイクルコールバックはその定義形式が定まっているため，通常のメソッド定義とは別に，ライフサ
イクルコールバックを定義するための記述を用意した．ライフサイクルコールバックの一般的な定義と，図
5.2に対応する定義例をそれぞれ図 5.12，図 5.13に示す．
ライフサイクルコールバックの定義は，lifecycleセクションで行う．表に示すように，定義したいライフサ
イクルコールバックに対応するレベル 3 のセクションを作成し，そのセクション内にライフサイクルコール
バックの処理内容をコードブロック記法で記述する．処理内容として扱うコードブロックは，セクション内に
最初に現れるものを対象とする．処理内容の記述に関しては，メソッド定義における方法に準ずる．
メソッド定義に対し，対象とするコードブロックの位置が異なるのは，ライフサイクルコールバックがコン
ポーネントの利用者によって明示的に呼び出されるものではないためである．そのため，コードブロックを使
用した説明を行う必要がないと考えたため，マークアップ構造およびスタイル定義の方法と同様にセクション
中の最初のコードブロックを用いるようにした．同様に，このセクションの内容はドキュメントへは出力され
ない．
第 5章 書式 28
表 5.3: ライフサイクルコールバックの種類
コールバック名 実行タイミング
createdCallback 独自タグのインスタンスの生成時attachedCallback 表示中の DOMツリーに挿入されたときdetachedCallback 表示中の DOMツリーから除去されたときattributeChangedCallback 属性値が追加・変更・削除されたとき
� �## lifecycle
### created‘‘‘javascript// createdCallbackの処理内容を定義‘‘‘
### attached‘‘‘javascript// attachedCallbackの処理内容を定義‘‘‘
### detached‘‘‘javascript// detachedCallbackの処理内容を定義‘‘‘
### attributeChanged‘‘‘javascript// attributeChangedCallbackの処理内容を定義‘‘‘� �
図 5.12: ライフサイクルコールバックの一般的定義
� �86 ## lifecycle8788 ### attached8990 クリックイベントに対するイベントハンドラの設定と91 すでに c o u n tプロパティが設定されていた場合、表示内容をそれにあわせる9293 ‘‘‘javascript94 this.$.container.addEventListener(95 "click", this._clickHandler.bind(this));9697 if (typeof this.count !== "number") {98 this.count = 0;99 }
100101 else {102 this.$.num.textContent = this.count;103 }104 ‘‘‘� �
図 5.13: 図 5.2に対応するライフサイクルコールバック定義の具体例
第 5章 書式 29
� �set: param {Number} value 新しくセットするカウンターの値: return {Number} 更新後のカウンターの値: test [0] 0: test [100] 100� �
図 5.14: テストコードの記述方法 1
� �## tests### suite-1テストスイートについての説明などを記入
‘‘‘javascriptit(’always pass’, function(){expect(true).to.be.ok;
});‘‘‘### suite-2
‘‘‘javascriptit(’always failed’, function(){expect(false).to.be.ok;
});‘‘‘� �
図 5.15: テストコードの記述方法 2
5.7 テストコードの記述
Python における doctest*3や，Lappalainen らの ComTest [9] のように，ドキュメントコメント中にテスト
コードを含めることでそのテストを実行するものやテストコードを生成するシステムが存在する．提案手法で
も，これらの手法を参考に，テストコードを生成するための記述を 2つ用意した．
1つ目の方法は，ComTestにならい，メソッド定義部分にテストコードを記述する方法である（図 5.14）．定
義リストの説明部分に「test [引数 1，引数 2，…] 期待値」といった記述を行うことで，メソッドに指定し
た引数値を与えて実行した結果が期待値になるかどうかをテストするコードを生成する．
2つ目の方法は，testsセクションにおいてテストコードを記述する方法である（図 5.15）．テストスイート
ごとにレベル 3のセクションを用意し，そのセクション内にテストコードをコードブロック記法を記述してい
く．セクション内のコードブロックの内容は全て，そのテストスイートにおけるテストコードとして使用され
る．なお，すべてのテストスイートからアクセス可能なテスト対象のコンポーネントの DOMインスタンスと
して，elmという変数が用意される．
生成するテストコードの形式や実行方法など，詳細は 6.6.4節にて述べる．
5.8 デモコードの記述
作成したWeb Componentsについて理解を深めさせるため，実際に使用しているデモを用意することは有用
である．そこで，作成しているWeb Componentsのデモコードを記述するための記法を用意した．一般的な定
義を図 5.16に示す．
デモコードの記述は demo セクションで行う．このセクション内の内容をデモコードを実行する HTML
*3 http://docs.python.jp/2/library/doctest.html
第 5章 書式 30
� �## demo
デモコード1の簡単な説明‘‘‘html<demo-code></demo-code>‘‘‘
デモコード2の簡単な説明‘‘‘html<demo-code></demo-code>‘‘‘
...� �図 5.16: デモコードの一般的定義
� �<!DOCTYPE html><html><head><title>Demo - demo-code</title><script src="bower_components/webcomponentsjs/webcomponents-lite.min.js"></script><link rel="import" href="./demo-code.html"><style>/* デモページのスタイル指定 省略 */</style>
</head><body><p>デモコード1の簡単な説明 </p>
<pre><code><demo-code></demo-code></code></pre>
<demo-code></demo-code>
<p>デモコード2の簡単な説明 </p>
<pre><code><demo-code></demo-code></code></pre>
<demo-code></demo-code>
</body></html>� �
図 5.17: 図 5.16より生成するデモコード
ファイルを生成するために使用する．デモコードはコードブロック記法で行う．コードブロック記法はそれぞ
れ別のデモコードとして解釈され，生成される HTMLファイルにその内容が展開される．生成するデモコー
ドを図 5.17に示す．解析後，demoセクションの内容は，この生成したデモコードを iframeで読み込む内容
へと変更される．デモコードを別の HTMLファイルへと出力することで，ネットワークを通じて公開する際
に，デモページとしてドキュメントとは別にアクセスすることが可能になる利点が得られると考えた．
5.9 メタ情報の記述
Markdown 記法を用いた文書作成において，文書のタイトルや著者名などのメタ情報は，Markdown 記法
が提供する記法で記述することは難しい．そこで，Jekyll*4や Middleman*5など，Markdown 文書から Web
ページを生成するシステムなどでは，Front Matter と呼ばれる記法を用意してこれに対処している．これは，
Markdown 文書の先頭に構造化データを記述可能な言語を用いてメタ情報を記述するというものである．現
在，Markdown文書においてメタ情報を記述する方法として，デファクトスタンダードとなっているといえる
手法である．
*4 https://jekyllrb.com/
*5 https://middlemanapp.com/
第 5章 書式 31
� �---authors:- ebisawa
keywords:- Web Components- document
year: 2016month: jan---
# my-counter## structure...� �
図 5.18: Front Matterの記述例
---で囲まれた範囲の内容が Front Matterに該当する．ここでは，YAMLを用いている．
提案手法においても，メタ情報を記述するために，Front Matter を採用する．Front Matterを記述するため
に用いる言語として，Front Matterを採用するシステムで広く使われている YAML*6を採用した．Front Matter
によるメタ情報の記述例を図 5.18に示す．
提案手法においては，著者情報のほか，依存する外部ライブラリや使用する外部ツールの指定などに用いる．
5.10 その他の記述
先に説明した記述以外にも，Markdown記法を用いて自由にドキュメントを記述することができる．ただし，
ドキュメント生成においては特に指定がない場合，先に説明したセクション以外の内容は取り除く．もし，生
成するドキュメントに含めておきたいレベル 2のセクションがあれば，見出し内容の最後に「:save」を加え
ることで残すことができる．また，これとは別に，ドキュメントの概要を記述するために descriptionセクショ
ンを作成することができる．
取り除いたセクションの情報は APIドキュメントの生成に使われないが，代わりに ReadMeとして，その情
報を使用する．生成する ReadMeの形式については，詳細を 6.6.3節にて述べる．
*6 http://www.yaml.org/
32
第 6章 実装
6.1 概要
第 4章で述べた提案手法での記述方法によって，実際にWeb Componentsのコードとそのドキュメントを生
成するシステムを作成した．作成したシステムのコードは，GitHubにて公開している*1．以下では，システム
の実装について述べていく．
6.2 開発環境
JavaScript を用いて，Node.js*2上で動作する CLI（CommandLine Interface）として作成した．使用した
Node.jsはバージョン 4.1.2のものを使用した．生成するWeb Componentsのソースコードは，ラッパーライ
ブラリである Polymerのバージョン 1.0を使用するものとした．また，生成するドキュメントの形式は HTML
とした．
Node.js上で動作するシステムとして実装した理由は，第 1章で取り上げたWeb開発に関わるシステムの多
くが Node.js上で実装されているためである．他のシステムと同じ実行環境上で動くことが，提案システムの
普及を考えた場合に大きな利点となると考えた．
6.3 処理の流れ
大まかな処理の流れは次のとおりである．
1. メタ情報抽出
2. 抽象構文木生成（6.4節）
3. 文書の解析
4. ソースコード生成（6.6.1節）
5. ドキュメント生成（6.6.2節）
6. その他の出力生成（6.6.3節，6.6.4節）
入力ファイルに対し，システムはまず Front Matter を解析し，メタ情報を抽出する．メタ情報を抽出後，
Markdown記法で記述された部分を解析し，抽象構文木を作成する．
作成した抽象構文木を走査して，Web Componentsのソースコード生成などに必要な情報とコード断片を抽
出する．それと同時に，抽象構文木の構造を操作することで，ドキュメントに不必要な情報を取り除く．走査
*1 https://github.com/e8l/wcWEB
*2 https://nodejs.org/en/
第 6章 実装 33
完了後，抽象構文木から HTMLに変換することでドキュメントを生成する．
収集した情報からWeb Componentsを構成するマークアップ構造（HTML），スタイル定義（CSS），API・
動作定義（JavaScript）を生成し，それらを組み合わせてWeb Componentsのソースコードを出力する．また，
同時にテストコードやデモコードの出力を行う．
最後に，生成したWeb Componentsに対して外部ツールを用いた処理を実行することで，システムの動作を
完了とする．
6.4 抽象構文木の作成
Markdown文書の内容を解析するために，文書構造をノードとして持つ抽象構文木を作成する．システムで
は，Markdown文書から抽象構文木を生成するために Pandoc*3を使用する．Pandocは，Markdown文書をは
じめとするさまざまな記法もしくは形式の文書から別のものへと変換するために用いられる，ドキュメント変
換ツールである．Pandocがサポートする出力形式として，文書構造を表す JSON（JavaScript Object Notation）
形式があるため，これを抽象構文木として取得する．図 4.2の Markdown文書を入力として，Pandocから得
られる JSON形式のデータの一部を図 6.1に示す．
図 6.1に示すように，Pandocから得られる抽象構文木は JavaScriptから直接扱うことができるものの，構造
の操作や情報収集のために走査するにはいささか扱い辛い形式となっている．そこで，システムではこの抽象
構文木からシステム内部向けに，DOMに似せたデータ構造を用いて抽象構文木を改めて作成する．このシス
テム内部向けの抽象構文木を用いて，ソースコード生成のための情報抽出やドキュメント生成のための文書構
造の変形を行う．
6.5 Polymerの使用に基づく記法の拡張
Web Componentsを作成するにあたり，Polymerを使用することによって，いくつかの便利な機能を用いる
ことができる．例えば，データバインディングの仕組みによって表示内容とプロパティの値を結びつけること
や，独自タグの属性値としてプロパティにアクセスすることが可能になるなどの機能が提供される．
このような機能を利用すべく，システムではプロパティおよびメソッド定義に関して，表 5.1および表 5.2
の内容以外にも解釈可能な項目を追加している．それぞれの追加内容を表 6.1，表 6.2に示す．独自タグの属
性値を通じて対応するプロパティの値を変化させることにより，動作の指定と変更する機能を強化かつ扱いや
すくするための，変更の通知（notify）や変更後の値のチェック（observer）といった機能が提供される．
6.6 出力の生成
6.6.1 ソースコードの出力
システムは，入力されたMarkdown文書を解析し，その記述内容やコードの断片を組み合わせることでWeb
Componentsのソースコードを生成する．
抽出した情報からソースコードを生成するために，システムでは予め用意しておいたソースコードのひな形
に対して，解析の結果得られた情報を展開することでこれを実現している．
*3 http://pandoc.org/
第 6章 実装 34
� �[{"unMeta": {}},[// 省略{"t": "Header","c": [1,["レベル1の見出しの別の記述例 ", [], []],[{"t": "Str", "c": "レベル1の見出しの別の記述例 "}]
]},{"t": "Header","c": [2,["レベル2の見出しの別の記述例 ", [], []],[{"t": "Str", "c": "レベル2の見出しの別の記述例 "}]
]},{"t": "Para","c": [{"t": "Str", "c": "空行から空行までの間が1つの段落として表現される。 "},{"t": "Space", "c": []},{"t": "Str", "c": "テキストについては"},{"t": "Space", "c": []},{"t": "Emph","c": [{"t": "Str", "c": "斜体"}
]},{"t": "Space", "c": []},{"t": "Str", "c": "もしくは"},{"t": "Space", "c": []},{"t": "Strong","c": [{"t": "Str", "c": "強調"}]
},{"t": "Space", "c": []},{"t": "Str", "c": "の装飾が可能。"}
]},// 省略{"t": "CodeBlock","c": [["", ["javascript"], []],"// プログラムコードの埋め込み例\ nconsole.log(\"Hello, world.\");"
]}
]]� �
図 6.1: Pandocから得られる JSON形式の抽象構文木の例（一部省略）
ひな形に対し，与えられたデータを展開した結果を生成する機構を一般にテンプレートエンジンと呼ぶ．シ
ステムでは，テンプレートエンジンの 1 つである Mustache*4を用いて，この処理を行う．Mustache は，図
6.2 に示すようなひな形を用意して使用する．ひな形中の「{{name}}」など，波括弧（{}）で 2 重に囲まれた
部分に与えられたデータの内容が展開される．また，{{#record}} と {{/record}} で囲まれた範囲の内容は，与えられたデータに record という名前のものがあった場合，record の要素の数だけ出力する．この範囲中の
「{{subject}}」「{{score}}」は，recordの要素が持つものとして参照する．図 6.2に対し，図 6.3に示すような
構造のデータを適用すると，Mustacheは図 6.4のようなテキストを生成する．
システムは，このような処理を 2 段階行うことで，ソースコードを生成する．まず，プロパティ定義・メ
ソッド定義・ライフサイクルコールバック定義などの情報から，Web Componentsの JavaScript部分に対応す
るコードを生成する．次に，生成した JavaScript部分のコードとマークアップ構造，スタイル定義などを組み
*4 https://mustache.github.io/
第 6章 実装 35
表 6.1: プロパティに関する記述可能な Polymerの機能
記述 意味
notify 値が変化した場合にイベントを発生させるreflect 値が変化した場合にタグの属性値も更新するreadOnly 値を更新不可（読み取り専用）にするobserver メソッド名 値が変更した場合にそれをチェックするメソッドを指定するcomputed メソッド名 (プロパティリスト) 指定したプロパティとメソッドから値が決定するようにする
表 6.2: メソッドに関する記述可能な Polymerの機能
記述 意味
observe プロパティ名 1, プロパティ名 2, ... 値の変更をチェックするプロパティを指定する
� �成績表
氏名: {{name}}学年: {{grade}}
科目名 | 成績-------------{{#record}}{{subject}} | {{score}}{{/record}}� �
図 6.2: Mustacheで使用するひな形の例
� �{"name": "Taro Tanaka","grade": "M2","record": [{"subject": "math","score": 90
},{"subject": "physics","score": 80
},{"subject": "english","score": 65
}]
}� �図 6.3: 図 6.2に適用するデータ
合わせて最終的なWeb Componentsのソースコードを生成する．
6.6.2 ドキュメントの出力
システムでは，入力された Markdown 文書を解析するために，抽象構文木を作成する．ドキュメントの生
成は，作成した抽象構文木を走査してソースコード生成に必要な情報を収集するのと同時にその構造を変形さ
せ，その抽象構文木を HTMLへ変換することで実現する．
第 6章 実装 36
� �成績表
氏名: Taro Tanaka学年: M2
科目名 | 成績-------------math | 90physics | 80english | 65� �
図 6.4: 図 6.2に図 6.3を適用することで得られるテキスト
抽象構文木へ行う変形操作は 3 種類である．1 つ目は，ドキュメントを生成するにあたり，作成する Web
Components のエンドユーザにとってドキュメントに必要のない情報を取り除くことである．例えば，コ
ンポーネント化する部分のマークアップ構造やそのスタイル定義に関するセクションの内容は，その Web
Componentsを使用するのみの場合にはドキュメントに不要である．そこで，このようなドキュメントを作成
する上で不要なセクションを走査の課程で取り除く．
2つ目は，文書構造の変形である．第 5章で述べたように，メソッドとプロパティの定義は定義リスト記法
を用いて定義していく．しかし，この文書構造をそのままにドキュメントを生成すると引数の説明が「param
{型名 } 引数名 説明」という定義そのものになってしまうなど，読み手にとって分かり辛いものになってしまう．そこで，一度抽象構文木から取り除き，収集した情報から改めてドキュメントとして提示するのに適
した文書構造によるものを挿入することでこれに対処する．挿入する内容は，ソースコードの生成と同様に，
Mustacheを用いてひな形から作成する．
3つ目は，情報の提示順序の標準化である．提案手法では，各セクションの記述順序を定めていない．そこ
で，入力されるMarkdown文書ごとにドキュメントでの情報の提示順序が変化してしまわないよう，一部の情
報についてはドキュメントでの提示位置が一定になるように抽象構文木の構造を変形させる．システムでは，
次のような順番で情報を提示するようにしている．
1. Web Componentsの名前（独自タグ名）
2. Web Componentsについての説明（descriptionセクションの内容）
3. Web Componentsのデモ（demoセクションの内容）
4. ドキュメントに残すことを指定したセクションの内容（入力Markdown文書での記述順序に合わせる）
5. プロパティについての説明（propertiesセクションの内容）
6. メソッドについての説明（methodsセクションの内容）
以上のように抽象構文木を変形させたあと，抽象構文木から HTMLへと変換することでドキュメントを生
成する．まず，抽象構文木をシステム内部向けの形式から，Pandocから得られた JSON形式の表現へと変換す
る．そして，Pandocを用いて JSON形式の抽象構文木を，HTMLへと変換する．最後に，得られた HTMLを
Mustacheを用いてデザインされた HTMLのひな形へと組み込むことでドキュメントを生成する．生成される
ドキュメントの例を図 6.5に示す．
第 6章 実装 37
図 6.5: 提案手法により生成されるドキュメント
6.6.3 ReadMeの出力
ドキュメント生成において，ドキュメントには不要であってもユーザに提示すべき情報はある．例えば，
OSS（OpenSource Software）として公開する場合のコントリビュートの仕方や，作成したWeb Components自
体もしくは使用しているライブラリなどのライセンス情報などがそれに当たる．そこで，いくつかの情報につ
いては，ドキュメントの代わりに ReadMeとしてその内容を出力する．
ReadMeとして出力される情報は，コンポーネント名と descriptionセクションの内容のほか，5.10節に該当
するセクションが対象となる．これらのセクションの内容をMarkdown記法のテキストへと再度戻し，それら
を 1つのファイルへと出力することで図 6.6のような ReadMeを作成する．
6.6.4 テストコードの出力
テストコードは，作成したWeb Componentsを読み込み，記述されたテストコードを実行するスクリプトが
記述された図 6.7のような HTMLファイルとして生成する．
第 6章 実装 38
� �my-counter========================================
シンプルなカウンターです。 クリックすると値を増やせます。
Demo----------------------------------------See [demo.html](./demo.html).
features----------------------------------------- シンプル- 軽い- 使いやすい
license----------------------------------------MIT� �
図 6.6: 生成する ReadMeの例
テストの実行には，Webブラウザで開くか web-component-tester *5というWeb Components用のテストツー
ルを用いる．テストコードは，JavaScriptのテストフレームワークである Mocha*6とアサーションライブラリ
である Chai*7を使用するものを生成する．
メソッド定義において記述したテストは，「Simple Assertion Test」というテストスイートの中にまとめ
て展開する．それ対して testsセクションで記述したテストコードは，レベル 3のセクションごとに別のテス
トスイートとして生成する．
6.7 外部ツール連携
第 1章で述べたように，コードのスタイルチェックや最適化など，様々なツールを自動的に実行することが
標準的となっている．そこで，Web Componentsのソースコード生成に関して，外部ツールを自動的に実行す
るための仕組みを用意している．
外部ツールの実行タイミングは 2つある．まず，Web Componentsを構成するマークアップ構造（HTML），
スタイル定義（CSS），API・動作定義（JavaScript）のコードが用意できた段階で，それぞれに対し外部ツー
ルを適用させる．ここでは，主にスタイルチェックや最適化などを行うことを想定している．その後，Web
Componentsのソースコードを生成した段階で，改めて外部ツールを実行させる．ここでは，テストの実行や
vulcanizeと呼ばれる特定環境での使用における最適化の実施を想定している．
外部ツール実行の指定は，Front Matter部で図 6.8に示すように行う．Web Componentsを構成する各種コー
ドが生成された段階で実行する外部ツールの指定は，preprocessというキーに，各種コードに対して実行す
るタスク名を記述したハッシュを指定することで行う．タスク名は配列で指定し，要素の順にタスクを実行す
る．タスク名と実際に実行する外部コマンドとの対応は，システムの設定ファイルにおいて予め用意しておく
（図 6.9）．Web Componentsのソースコードを生成した後に実行する外部ツールの指定は，aftercommandと
いうキーに，実行するタスク名を記述した配列を指定することで行う．こちらも，要素の順にタスクを実行す
る．予めシステムの設定ファイルにタスク設定を用意しておく点も同様である．
また，Web Components のコードの記述に代替言語を用いた場合，そのトランスパイル処理のために外部
*5 https://github.com/Polymer/web-component-tester
*6 http://mochajs.org/
*7 http://chaijs.com/
第 6章 実装 39
� �<!doctype html><html><head><title>Test Page for my-counter</title><meta charset="utf8"/>
<!-- testing framework --><link rel="stylesheet" href="../bower_components/mocha/mocha.css"/><script src="../bower_components/chai/chai.js"></script><script src="../bower_components/mocha/mocha.js"></script><script>mocha.setup("bdd");</script>
<!-- target web component --><script src="../bower_components/webcomponentsjs/webcomponents-lite.min.js"></script><link rel="import" href="../my-counter.html"/>
</head><body><!-- component instance --><my-counter id="elm"></my-counter><!-- result --><div id="mocha"></div><!-- test --><script>var assert = chai.assert,
expect = chai.expect,should = chai.should;
var elm = document.getElementById("elm");
describe("my-counter", function(){describe("Simple Assertion Test", function(){it("set-1", function() {assert.equal(elm.set(0), 0);
});
it("set-2", function() {assert.equal(elm.set(100), 100);
});
});});
describe("suite-1", function(){it(’always pass’, function(){expect(true).to.be.ok;
});
});
describe("suite-2", function(){it(’always failed’, function(){expect(false).to.be.ok;
});
});
});
mocha.checkLeaks();if (window.mochaPhantomJS) {mochaPhantomJS.run();
}else {mocha.run();
}</script>
</body></html>� �
図 6.7: 生成するテストコードの例
第 6章 実装 40
� �---preprocess:html: [minimize]css: [minimize]js: [lint,minimize]
aftercommand: [test]---� �
図 6.8: 外部ツール実行のための Front Matter部の記述例
� �{"command": {"minimize": {"command": "htmlmin"},"test": {"command" : "wct", "noArgs": true},"vulcanize": {"command": "vulcanize", "option": ["--inline-css", "--inline-scripts"]}
},"preprocess": {"html": {"minimize": {"type": "command", "command": "htmlmin", "option": ["--nojsmin", "--nocssmin"]}
},"js": {"lint": {"type": "command", "command": "jshint", "option": ["-"], "noUpdate": true}"minimize": {"type": "command", "command": "uglifyjs"},
},"css": {"minimize": {"type": "command", "command": "cleancss"}
}}
}� �図 6.9: 外部ツール実行のためのシステム設定ファイル
� �{"compiler": {"scss": {"type": "command", "command": "scss"},"sass": {"type": "command", "command": "sass"},"less": {"type": "command", "command": "less", "option": ["-"]},"haml": {"type": "command", "command": "haml"},"slim": {"type": "command", "command": "slimrb", "option": ["-p"]}
}}� �
図 6.10: 代替言語使用のためのシステム設定ファイル
ツールを実行する．代替言語を用いて図 5.5・図 5.7・図 5.11 と同様の記述を行った場合の例を，図 6.11 に
示す．structureセクションおよび styleセクションのマークアップ構造とスタイル定義の記述においては，図
6.11の 2行目および 11行目のようにコードブロック記法においてコード種類を明記することで，そのコード
種類に対して図 6.10に示すシステムの設定ファイルにおいて指定された外部ツールを用いて HTML，CSSへ
の変換処理を行う．メソッドおよびライフサイクルコールバックの処理内容の定義においては，システム実
行時に動作オプションを指定することによって JavaScriptの代わりに図 6.11の 45行目から 52行目のように
CoffeeScriptで記述行うことを選択することができる．ただし，JavaScriptによる定義との混在はできない．ま
た，ECMAScript2015の機能を用いて記述している場合動作オプションを指定することで，対応していないブ
ラウザ向けに従来の仕様での記述へ変換する処理を外部ツールを用いて行うようにすることも可能である．
第 6章 実装 41
� �1 ## structure2 ‘‘‘haml3 #container4 #heart5 #count6 %span#num7 LIKE8 ‘‘‘9
10 ## style11 ‘‘‘scss12 $fontSize: 16px;13 $padding: 2px;1415 @mixin sameHeight {16 font-size: $fontSize;17 line-height: $fontSize + $padding*2;18 height: $fontSize + $padding*2;19 }2021 #container {22 display: inline-block;23 @include sameHeight;24 padding: 0 $padding*2;25 font-family: sans-serif;26 color: #223;27 background-color: #4CCFFF;28 border: 1px solid #0084B4;29 border-radius: $padding;30 cursor: pointer;31 }3233 // 以下省略34 ‘‘‘3536 ## methods3738 set39 : param {Number} value 新しくセットするカウンターの値40 : return {Number} 更新後のカウンターの値4142 カウンターの値を引数の数値に更新する。43 引数の数値は四捨五入によって整数値に丸められる。4445 ‘‘‘coffeescript46 return @count if !value or typeof value isnt number4748 @count = Math.round(value)49 @$.num.textContent = @count5051 @count52 ‘‘‘5354 以下省略� �
図 6.11: コード片の記述に代替言語を用いる例
42
第 7章 考察
7.1 概要
以下では，本研究の提案手法について，その特徴などを考察する．
また，実装したシステムを用いて，GitHubで公開されている 7種のWeb Componentsを提案手法で記述す
ることを行った．実際に提案手法でWeb Componentsのコードを記述することにより気づいたことなども，こ
こで考えていく．
7.2 提案手法による記述性
提案手法は，文芸的プログラミングの手法を踏襲することでWeb Componentsでもドキュメントを同時に作
成できるようにし，そこに一定の記述形式を定めることでドキュメントコメントによる方式と同様の利点を得
るものである．その上で，ドキュメントコメントによる手法と比べて利点と考えられる点がいくつかある．
提案手法では，従来手法を採用した場合と比較し，Web Componentsの定義に必要な記述量を抑えられると
考えられる．例えば，ドキュメントコメントを用いた手法の場合，図 3.1の 11-12行目と 15行目のようにド
キュメントコメントとソースコードとでそれぞれメソッドの引数名を記述する必要がある．しかし，提案手法
では図 5.11の 50-51行目や 68-69行目のように，1つの記述によってドキュメントの情報とソースコードの内
容を記述することができる．このように，重複していた記述を行わない分，記述量を削減できると考えられる．
加えて，重複した記述を取り除くことで，ドキュメントとソースコードの記述の乖離をいくらか軽減する作用
もあると考えられる．
また，提案手法ではドキュメントやテストだけではなく，実際にコードを生成することができる．つまり，
先に作成しようとしているWeb Componentsの API仕様などを先に定めておき，後からその処理内容などの
実装にとりかかることができる．このことから，ドキュメント駆動開発 [11]や ReadMe駆動開発*1などの開発
手法との親和性が高いと考えられる．
一方で，提案手法について，より検討しなければならないこともある．まずは，提案手法そのものの記法で
ある．提案手法では，拡張記法である定義リスト記法を使用しているものの，すべてMarkdown記法で記述を
行う．そのため，レベル 2の見出しでセクション分けしていく，定義リスト記法でメソッドやプロパティの概
要を定義する，セクション中の最後のコードブロックの内容を実装のコードとして用いる，などの記述に関す
るルールが逆にドキュメントの記述を困難にしてしまっている可能性がある．また，ドキュメント記述の自由
度を上げるために拡張記法を用いたが，記述の自由度を損なわずに標準の記法のみでメソッドやプロパティな
どの定義を行えるような記法を考える必要もあるかもしれない．これに関しては今後も深く検討してく必要が
*1 http://tom.preston-werner.com/2010/08/23/readme-driven-development.html
第 7章 考察 43
ある．
また，提案手法では作成した文書から一度 Web Components のコードを生成する必要がある．一方で，ド
キュメントコメントはコメントであるために，そのままコンパイルすることや処理系に渡して実行することが
できる．そのため，作成したコードを動作させることに手間がかかってしまっている．このことから，従来通
り，ソースコードとドキュメントとを個別に作成するほうがよいとの意見もあった．加えて，Web Components
をデバッグする場合にも，問題が発生した箇所と提案手法における記述箇所の対応付けが難しいという問題が
ある．提案手法で記述した文書を，そのままWeb Componentsとして動作させるための JavaScriptライブラリ
を実装することで，前者の問題を解決できる可能性がある．後者の問題に関しては，すでに SourceMap*2 とい
う代替言語からの変換もしくは最小化を行った場合のコードと元のコードとの対応付けを行うための仕組みが
ある．そのため，提案手法においてもソースコード生成に際して SourceMapを出力するようにすることで，こ
の問題を解決できると考えられる．
7.3 実使用から得られた改善点
GitHubにて公開されているWeb Componentsのコードを対象に，以下に列挙する Polymerを使用して作成
されているものを，提案手法により記述した．それにより，提案手法に対する改善点が得られた．ここでは，
得られた改善点について述べる．
• double-bounce-spinner*3 ─ローディングアニメーションを表示する
• neon-text-board*4 ─アニメーションによる切り替え機能のついたテキストボード
• poly-action-block*5 ─表示内容が自動的に切り替わるボタン UI
• polymer-zoom-image*6 ─マウス付近を拡大して表示することのできる画像表示 UI
• simple-color-picker*7 ─シンプルな色の選択を行うための UI
• Sortable*8 ─マウス操作による並び替えが可能なリスト表示機能を提供する
• table-element*9 ─データに応じた TODOリストを表示する（付録 Bにて提案手法による記述例を提示）
この研究は，Web Componentsについてドキュメントとソースコードの同時生成を可能にするため，提案手
法もドキュメントに情報を提示することを前提とした記法を用意している．しかしながら，この前提によって
記述の煩雑さが大きくなってしまう場合があった．
SortableというWeb Componentsでは，公開プロパティおよびそれに対応づけられた独自タグの属性値を変
更することで，動作を切り替える構造になっていた．その実装は，プロパティごとに設定されたメソッドがプ
ロパティの値の変化に合わせて自動的に呼び出され，その値の変化に応じて実装に使用しているライブラリの
設定を切り替えるものであった．各メソッドは構造がほとんど同一であり，ドキュメントあるいは実装におけ
るコメントとして残すべき記述が必要ないものであった．オリジナルのコードでは図 7.1のような形式により
コードを記述するだけで事足りるのだが，提案手法の場合では図 7.2のように記述する必要があり，オリジナ
*2 https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit?pref=2&pli=1
*3 https://github.com/JaySunSyn/double-bounce-spinner
*4 https://github.com/Collaborne/neon-text-board
*5 https://github.com/reinier-brummelkamp/poly-action-block
*6 https://github.com/alexisgeneau/polymer-zoom-image
*7 https://github.com/astelmashenko/simple-color-picker
*8 https://github.com/RubaXa/Sortable
*9 https://github.com/charbelrami/table-element
第 7章 考察 44
� �Polymer({properties {prop1: {type: Number, value: 123, observer: "_prop1Changed"},prop2: {type: String, value: "foo", observer: "_prop2Changed"},prop3: {type: Boolean, value: true, observer: "_prop3Changed"},// ...
}
_prop1Changed: function(val) { ... },_prop2Changed: function(val) { ... },_prop3Changed: function(val) { ... },// ...
})� �図 7.1: 提案手法により記述が煩雑になってしまうWeb Componentsの定義例（API定義部のみ）
� �## propertiesprop1: type Number: ‘123‘: observer _prop1Changed
prop2: type String: ‘"foo"‘: observer _prop2Changed
prop3: type Boolean: ‘true‘: observer _prop3Changed
## methods_prop1Changed: private: param {Number} val New Value
‘‘‘javascript
...
‘‘‘
_prop2Changed: private: param {String} val New Value
‘‘‘javascript
...
‘‘‘
_prop3Changed: private: param {Boolean} val New Value
‘‘‘javascript
...
‘‘‘})� �
図 7.2: 図 7.1の提案手法での記述
ルのコードよりも記述コストが高くなる結果となった．
このWeb Componentsは特殊な例と言えるが，実際に公開 APIよりも内部処理のための非公開 APIの方が
多い例がよく見受けられた．このことから，現在の非公開 APIの記述方法に加え，一括して非公開 APIを定
義するための記法を用意すべきだと考えられる．また，この例においてはプロパティ定義において，値の変動
によって呼び出される処理内容が単純な非公開メソッドの定義を行えるようにすることで，より抜本的な解決
に繋がると考えられる．
第 7章 考察 45
7.4 ドキュメントの多言語化
提案手法について指摘された内容の 1つとして，多言語版のドキュメントを作成する場合の問題が挙げられ
る．これは提案手法に限らず，ソースコードとドキュメントを同時作成しようとする手法において問題となる．
ドキュメントコメントを用いる方法の場合，例えば日本語と英語のドキュメントコメントを 2つ用意してお
き，一方をドキュメントコメント，他方を通常のコメントと切り替えることによって対処することが可能であ
る．しかしながら，提案手法はドキュメントコメントを用いる方法ではなく，またMarkdown記法にはコメン
ト記法が存在しないため採用することはできない．現状取りうる手段としては，ある言語でのドキュメントを
作成するためだけに提案手法で記述した文書のコピーを作成し，その文書中のドキュメントに表示される部分
のみを翻訳する方法が現実的である．
7.5 エディタの提案手法への対応
提案手法を普及させることを考えた場合，提案手法での記述に対し，エディタがどの程度対応可能なのかが
重要になる．主要なプログラミング言語について，その構文要素を色分けもしくはスタイル分けするシンタッ
クスハイライトの機能や，コードの推薦や補完機能を提供することは当たり前のようになっている．特にシン
タックスハイライトは，Sarkarの研究によればソースコード中のコンテキストの切り替えを削減し，初学者ほ
どプログラムの構造を理解させる助けとなる [13]とされる重要な機能である．提案手法についても，これらの
機能を従来の枠組みの中で提供可能なのかどうかを考えることは，とても重要であると言える．
まず，シンタックスハイライトについて考える．提案手法では，Markdown 記法の中に複数種類のプログ
ラミング言語で記述されたコード片が埋め込まれた文書を作成する．そのため，Markdown記法の文書構造，
および埋め込まれたコードが適切にシンタックスハイライトされればよいと考えられる．Vim*10，Sublime
Text*11，Atom*12ではそれぞれにMarkdown文書に対するシンタックスハイライトのためのプラグインを導入
することで実現することができた（図 7.3）．よって，シンタックスハイライトに関しては，従来の枠組みのみ
でサポートすることが可能であると言える．
次に，コードの推薦および補完機能について考える．Vimでは，最近入力した内容を元に，入力しようとし
ている単語を補完する機能を持っている．また，多くのエディタにおいて，予め決まった内容を登録しておい
て必要なときにそれを貼り付けるための機能が用意されている．そのため，文脈によらない入力内容の推薦や
補完については，従来の枠組みでサポートされているということができる．しかしながら，コンテキストに応
じた入力内容の推薦や補完はサポートされていない．その理由は，Markdown記法で記述された文書との区別
がなく，またMarkdown記法を用いてプログラミングを行うことがないためである．しかし，もしコードの推
薦・補完機能がMarkdown記法で記述された文書に埋め込まれたコードに対応していた場合でも，そのまま提
案手法に適応することはできない．なぜなら，プロパティやメソッドの定義の一部をコードからMarkdown記
法でのドキュメント記述へ移しているためである．これに対応するためには，Markdown記法やその文書構造
についても解析した上で推薦・補完する必要があり，提案手法のために別途そのような機能を作成する必要が
ある．
*10 http://www.vim.org/
*11 http://www.sublimetext.com/
*12 https://atom.io/
第 7章 考察 46
図 7.3: テキストエディタ AtomにおけるMarkdown記法のシンタックスハイライトの例
7.6 変換システムの動作について
現在，システムは入力として渡された文書を処理してWeb Componentsのソースコードとドキュメントを作
成するための最低限の機能のみを実装しているため，記述の誤りやその可能性がある場合の通知機能が不足し
ている．例えば，入力文書に structureセクションが見つからなかった場合に，structureセクションを処理しな
かったことをユーザに伝えるなどの処理は現在行っていない．
提案手法ではドキュメントの記述をベースにコードを定義していく必要があるため，通常のプログラミング
言語よりも厳密に誤りに気付く必要がある．そのために，このような機能を充実させることで，記述の誤りに
気付きやすくすることが可能になると考えられる．同様に，引数も返り値もないメソッド定義の記述方法など，
現時点ではファジーな記法自体をより形式化することによってこれを強化することが可能だと考えられる．そ
の一方で，このような機能を充実させることにより，ドキュメント記述の制約を課しすぎてしまう可能性があ
る．望み通りのソースコードを生成するために，本来の目的であるドキュメントの記述を不自由にしてしまう
ことがないよう注意しなければならない．
また，現在はドキュメント記述から得られる情報と実装との乖離を確認する機能はないが，これを提供する
ことによって提案手法による開発効率を向上させることができると考えられる．例えば，メソッドの戻り値の
型の指定とその実装における戻り値のチェックを行い，ソースコードを生成する時点でコードの誤りなどを指
摘することが可能になる．現実的な問題として，システムがチェック可能な内容はあまり多くないと想定され
るが，実装を検討すべき機能であるといえよう．
47
第 8章 関連研究
8.1 ドキュメント生成
ソースコードとドキュメントを同時に生成するための手法については，第 3章で示したように，ドキュメン
トコメントを用いる手法と，文芸的プログラミング [6]の 2つが挙げられる．
ドキュメントコメントを用いる方法の実例としては，Java言語における JavaDocが代表的である．JavaDoc
を用いた APIドキュメントの生成について，Kramerはそのプロセスやガイドラインについて述べている [7]．
Lappalainenらは図 8.1のようにドキュメントコメントに記述したテストコードから，テストフレームワーク
である JUnit*1で実行するためのユニットテストコードを生成するツールである ComTestを開発し，その有用
性をプログラミングの講義での使用によって示している [9]．
文芸的プログラミングの手法を応用した例としては，Hillenbrandらの Ginger[5]が挙げられる．ドキュメン
トを生成する際に，埋め込まれたコードを実行することで得られるグラフを挿入することができ，コンピュー
タグラフィックスの講義で活用している．
� �public class SmallestDivisor {/*** Function finds the smallest divisor for given* number** @param n number to be studied* @return smallest divisor for n, 1 if n is a prime* @example* <pre name="test">* smallestDivisor(1) === 1;* smallestDivisor(2) === 1;* smallestDivisor(3) === 1;* smallestDivisor(4) === 2;* smallestDivisor(5) === 1;* smallestDivisor(6) === 2;* </pre>*/public static int smallestDivisor(int n) {for (int i=2; i<=n/2; i++)if ( n % i == 0 ) return i;
return 1;}// The traditional way of students to test a procedure// or module, indicating restricted test coverage.public static void main(String[] args) {int n = 25;int divisor = smallestDivisor(n);System.out.println(divisor);
}}� �
図 8.1: ComTestによるテストコードの記述例（文献 [9]より引用）
*1 http://junit.org/
第 8章 関連研究 48
図 8.2: CTSの例（文献 [3]より引用）
8.2 コンポーネント化技術
本研究ではWeb ページ中の構成要素をコンポーネント化する仕組みとして，現在W3C で仕様策定段階の
Web Componentsを対象としたが，コンポーネント化の仕組みについては様々なものが提唱されている．
Benson らは，Cascading Tree Sheet（以下 CTS）というコンポーネント化の仕組みを提唱している [3]．
CTS の例を図 8.2 に示す．CTS では，コンポーネントを使用する部分のマークアップ構造と，コンポーネン
トの実装のマークアップ構造との対応付けを行うことでコンポーネント化を実現する．図 8.2 においては，
widget.cts を読み込んだ HTML 内に存在する，クラス属性に vertically-center を指定したタグを対象と
して widget.htmlのマークアップ構造へと書き換える．書き換え前に対象となるタグの子要素は，書き換え後
の widget.htmlのマークアップ構造におけるクラス属性が c-wrapperの div要素の子要素となる．Bensonは
CTSを活用した手法によってWebページの編集におけるコストを削減できることを示し [2]，CTSを活用し
た新たなWeb開発手法を提案している [1]．
山本らは，Copというコンポーネント化およびその利用のためのフレームワークを提唱している [14]．コン
ポーネントを構成する HTML，CSS，JavaScriptとコンポーネントに関するメタ情報を記述したファイルを用
意し，それらを結合してコンポーネントを表現する 1つの JavaScriptファイルを生成する．実行時ライブラリ
がこの JavaScriptファイルの内容を解釈することで，コンポーネントを使用することができる．仕様策定段階
のWeb Componentsとは異なり，従来の枠組みでコンポーネント化を実現することが可能なため，古いブラウ
ザにも対応できる手法であることを利点に挙げている．
コンポーネント化とは少し異なるが，HanらはWebページの構成要素を Pageletと呼ばれる単位に分割して
行うWebアプリケーションの開発手法を提案している [4]．ページごとに変化する部分の構造を XMLおよび
XSLTで記述し，必要なデータを元にクライアントサイドで HTMLを生成する．XMLおよび XSLTから生成
することで 1 種のコンポーネント化を実現するほか，キャッシュ機能により通信量の削減を見込むことがで
きる．
Web Componentsを扱う研究は少ないが，KrugらはWeb Componentsで作成した SmartCompositionという
システムを提案している [8]．このシステムは，複数のデバイス間での同期機能を提供する Web アプリケー
ション作成を支援する．
第 8章 関連研究 49
図 8.3: Madokoにおける文書作成の様子
8.3 Markdown記法
Markdown記法を対象とした研究は主に文書作成を主としているものが多い．
Poley は Markdown 記法を用いてWeb ページを作成するためのシステム，RUMU Editor を開発した [12]．
Markdown 記法から HTML を生成する際に，Blueprint*2という CSS フレームワークと組み合わせることで
Webページを作成する．LeijenはMarkdown記法を用いて，数式やプログラムコードなどが含まれる，論文な
どの複雑な文書を作成するシステムMadokoを開発した [10]．Madokoはオンラインエディタとして公開*3さ
れており，HTML 形式の文書のほか，LATEX を通じて PDF 形式の文書を生成することができる．図 8.3 に
Madokoを用いた文書作成の様子を示す．
文書作成を主とするものが多い一方で，それとは異なる用途のために使用されている例もある．API
Blueprint*4は，Markdown 記法により WebAPI の定義を作成するための記法である．図 8.4 に示すような
Markdown 文書から図 8.5 のような WebAPI を定義した情報を表す JSON データを出力する．API Blueprint
の内容からドキュメントを作成するツールやモックサーバを構築するツールが公開されており，対象が異なる
ものの，提案手法と類似した技術であるといえる．
*2 http://www.blueprintcss.org/
*3 https://www.madoko.net/
*4 https://apiblueprint.org/
第 8章 関連研究 50
� �# GET /message+ Response 200 (text/plain)
Hello World!� �図 8.4: API Blueprintにおける最も簡単なWeb APIの定義例
� �{"element": "parseResult","content": [{"element": "category","meta": {"classes": ["api"], "title": ""},"content": [{"element": "category","meta": {"classes": ["resourceGroup"], "title": ""},"content": [{"element": "resource","meta": {"title": ""},"attributes": {"href": "/message"},"content": [{"element": "transition","meta": {"title": ""},"content": [{"element": "httpTransaction","content": [{"element": "httpRequest", "attributes": {"method": "GET"},"content": []},{"element": "httpResponse","attributes": {"statusCode": "200","headers": {"element": "httpHeaders","content": [{"element": "member","content": {"key": {"element": "string", "content": "Content-Type"},"value": {"element": "string", "content": "text/plain"}
}}
]}
},"content": [{"element": "asset","meta": {"classes": ["messageBody"]},"attributes": {"contentType": "text/plain"},"content": "Hello World!\n"
}]
}]
}]
}]
}]
}]
}]
}� �図 8.5: 図 8.4より生成されるWeb APIを定義する JSON
51
第 9章 結論
9.1 まとめ
本研究では，Web Componentsを対象に，ソースコードとドキュメントを同時に生成するための手法を提案
した．
その手法として，文芸的プログラミングのようにMarkdown記法を用いたドキュメント記述中にコード片を
埋めこみ，そこからソースコードとドキュメントを生成するというものを採用した．記述にあたり，一定の形
式化および制限を加えることでドキュメントコメントを用いる手法と同様の利点を得られるようにした．
この手法によりソースコードとドキュメントを生成することができるシステムを実装し，実際に提案手法に
よりWeb Componentsの定義を行った．その体験と対外発表での議論から，提案手法の特徴や利点，改善点な
どを考察した．Web Componentsのソースコードとドキュメントの同時生成が行えるようになり，従来の方法
と比べて記述内容の重複を減らせるという利点がみられるが，ドキュメントに提示しないメソッドの定義やデ
バッグの困難性などの改善点がある．
9.2 今後の課題
9.2.1 定性的，定量的な分析
現時点では，提案手法の有用性を実験を通じて評価できていない．これは，Web Components自体が仕様策
定段階にあるため，被験者実験を行うことが困難であるためである．
今後は提案手法の有用性を評価するために，実験の計画を進めていきたい．
9.2.2 記法の改善
第 7章で考察したように，提案手法には記法について改善すべき点が見られる．
現時点で確認できている，ドキュメントに掲載する必要のないメソッドの定義に関しては，早急に対策を考
えたい．また，可能ならば実験結果も踏まえた上で，より効率よく記述ができるように記法を改善していき
たい．
第 9章 結論 52
9.2.3 システムの改良・関連ツールの実装
提案手法による記述だけではなく，それを処理するシステムについても改良が必要である．
SourceMapの出力や，記述内容と実装の乖離チェックなど，デバッグや記述の誤りを気付きやすくするため
の機能を中心に改良を進めていきたい．
また，提案手法に対する関連ツールの開発も，今後の課題として挙げられる．現状では一度処理系を用いて
Web Componentsのコードを生成する必要があるが，提案手法で記述した文書自体をWeb Componentsとして
使用するためのライブラリを作成することは，今後の発展に有用であるといえる．
53
謝辞
本研究は，電気通信大学大学院情報理工学研究科情報・通信工学専攻の寺田研究室において，寺田実准教
授のご指導のもと行われました．
寺田実准教授には，研究の方針の検討やアイディアの提供など，数多くのご助言とご指導を賜りました．心
からお礼を申し上げます．
明星大学情報学部情報学科の丸山一貴准教授には，研究についてご助言とご指導を賜りました．深く感謝致
します．
また，寺田研究室の仲間である修士課程 2年の長利槙吾さん，齊藤令さん，修士課程 1年の阿部真之さん，
鈴木佑樹さん，平田吉久さん，本田裕人さん，学部 4年の安部文紀さん，布川大地さん，山本愛美さん，渡
辺友康さん，渡邊裕貴さん，そして OBOGの皆様には研究について多くのアイディアやアドバイスをいただ
き，また研究室での生活などさまざまな面でお世話になりました．心からの感謝を申し上げます．
54
参考文献
[1] Edward Benson. Mockup Driven Web Development. In Proceedings of the 22Nd International Conference
on World Wide Web, WWW ’13 Companion, pp. 337–342, Republic and Canton of Geneva, Switzerland,
2013. International World Wide Web Conferences Steering Committee.
[2] Edward Benson. Quantifying and Reducing the Cost of Web Edits. In CHI ’13 Extended Abstracts on Human
Factors in Computing Systems, CHI EA ’13, pp. 2659–2664, New York, NY, USA, 2013. ACM.
[3] Edward O. Benson and David R. Karger. Cascading Tree Sheets and Recombinant HTML: Better Encapsu-
lation and Retargeting of Web Content. In Proceedings of the 22Nd International Conference on World Wide
Web, WWW ’13, pp. 107–118, Republic and Canton of Geneva, Switzerland, 2013. International World Wide
Web Conferences Steering Committee.
[4] Hao Han and Bo Liu. Problems, Solutions and New Opportunities: Using Pagelet-based Templates in Devel-
opment of Flexible and Extensible Web Applications. In Proceedings of the 12th International Conference
on Information Integration and Web-based Applications& Services, iiWAS ’10, pp. 679–682, New York,
NY, USA, 2010. ACM.
[5] Eddie Hillenbrand and James Dean Palmer. Writing Software to Be Understood: An Exercise in Ginger
Using Literate Programming. J. Comput. Sci. Coll., Vol. 26, No. 2, pp. 106–112, December 2010.
[6] Donald E. Knuth. Literate Programming. Comput. J., Vol. 27, No. 2, pp. 97–111, May 1984.
[7] Douglas Kramer. API Documentation from Source Code Comments: A Case Study of Javadoc. In Proceed-
ings of the 17th Annual International Conference on Computer Documentation, SIGDOC ’99, pp. 147–153,
New York, NY, USA, 1999. ACM.
[8] Michael Krug and Martin Gaedke. SmartComposition: Enhanced Web Components for a Better Future of
Web Development. In Proceedings of the 24th International Conference on World Wide Web, WWW ’15
Companion, pp. 207–210, Republic and Canton of Geneva, Switzerland, 2015. International World Wide
Web Conferences Steering Committee.
[9] Vesa Lappalainen, Jonne Itkonen, Ville Isomottonen, and Sami Kollanus. Comtest: A Tool to Impart TDD
and Unit Testing to Introductory Level Programming. In Proceedings of the Fifteenth Annual Conference on
Innovation and Technology in Computer Science Education, ITiCSE ’10, pp. 63–67, New York, NY, USA,
2010. ACM.
[10] Daan Leijen. Madoko: Scholarly Documents for the Web. In Proceedings of the 2015 ACM Symposium on
Document Engineering, DocEng ’15, pp. 129–132, New York, NY, USA, 2015. ACM.
[11] Luqi, Lin Zhang, Valdis Berzins, and Ying Qiao. Documentation driven development for complex real-time
systems. IEEE Trans. Softw. Eng., Vol. 30, No. 12, pp. 936–952, December 2004.
参考文献 55
[12] Eleanor Poley. RUMU Editor: A non-WYSIWYG Web Editor for Non-technical Users. In CHI ’10 Extended
Abstracts on Human Factors in Computing Systems, CHI EA ’10, pp. 4357–4362, New York, NY, USA, 2010.
ACM.
[13] Advait Sarkar. The impact of syntax colouring on program comprehension. In PPIG 2015 - 26th Annual
Workshop, Vol. 2015, jul 2015.
[14] 山本竜太郎,岩崎英哉. Cop: 部品化を指向したWebアプリケーション開発の枠組. 第 57回プログラミン
グシンポジウム予稿集, pp. 119–129, jan 2016.
56
付録
A: 図 5.2の完全版のコード� �1 <link rel="import" href="bower_components/polymer/polymer.html">234 <dom-module name="my-counter">5 <template>6 <style>7 #container {8 display: inline-block;9 font-size: 16px;
10 line-height: 20px;11 height: 20px;12 padding: 0 4px;13 font-family: sans-serif;14 color: #223;15 background-color: #4CCFFF;16 border: 1px solid #0084B4;17 border-radius: 2px;18 cursor: pointer;19 }2021 #container #heart, #container #count {22 display: inline-block;23 }24 #heart:before {25 content: "\2764";26 color: #BE1931;27 }28 #count {29 color: #fff;30 -webkit-user-select: none;31 }32 #count > #num {33 font-family: monospace;34 font-weight: bold;35 }36 </style>37 <div id="container">38 <div id="heart"></div>39 <div id="count">40 <span id="num"></span> LIKE41 </div>42 </div>43 </template>44 <script>45 (function() {464748 Polymer({49 is: "my-counter",5051 properties: {52 count: {53 type: Number,54 value: 055 }56 },5758 _callback: undefined ,596061 attached: function() {62 this.$.container.addEventListener(63 "click", this._clickHandler.bind(this));6465 if (typeof this.count !== "number") {66 this.count = 0;67 }
付録 57
6869 else {70 this.$.num.textContent = this.count;71 }72 },737475 set: function( value ) {76 if (!value || typeof value !== "number") {77 return this.value;78 }7980 this.count = Math.round(value);81 this.$.num.textContent = this.count;8283 return this.count;84 },8586 increase: function( value ) {87 if (!value || typeof value !== "number") {88 value = 1;89 }9091 this.count += Math.round(value);92 this.$.num.textContent = this.count;9394 return this.count;95 },9697 reset: function( ) {98 this.count = 0;99 this.$.num.textContent = "0";
100 },101102 onClicked: function( callback ) {103 if (typeof callback === "function") {104 this._callback = callback;105 }106 },107108 _clickHandler: function( event ) {109 ++this.count;110 this.$.num.textContent = this.count;111112 if (this.count < 0) {113 this.reset();114 }115116 if (this._callback) {117 this._callback(event);118 }119 }120 });121 })();122 </script>123 </dom-module>� �
付録 58
B: 7.2節で行った提案手法での記述の一例（table-element）� �1 ---2 load: [../iron-ajax/iron-ajax.html, ../paper-input/paper-input.html]3 author: Charbel Rami4 license: MIT5 ---6 # table-element7 ## structure8 ‘‘‘html9 <iron-ajax url="{{url}}" handle-as="json" last-response="{{data}}" auto></iron-ajax>
10 <paper-input value="{{search}}" label="{{searchLabel}}"></paper-input>11 <table>12 <thead>13 <tr>14 <template is="dom-repeat" items="{{keys}}">15 <th>{{item}}</th>16 </template>17 </tr>18 </thead>19 <tbody>20 <template is="dom-repeat" items="{{data}}" filter="{{computeFilter(search)}}">21 <tr hidden$="{{isHidden(item)}}">22 <td>{{item.userId}}</td>23 <td>{{item.id}}</td>24 <td>{{item.title}}</td>25 <td>{{item.completed}}</td>26 </tr>27 </template>28 </tbody>29 </table>30 ‘‘‘31 ## properties32 url33 : type String3435 no detail3637 hiddenKey38 : type String3940 no detail4142 searchKey43 : type String4445 no detail4647 searchLabel48 : type String49 : ‘’search’‘5051 no detail5253 ## methods54 _getData55 : private56 : param {Object} obj no detail57 ‘‘‘javascript58 var keys = Object.keys(obj);59 this.keys = Object.keys(obj[keys[1]][0]);60 ‘‘‘6162 isHidden63 : param {Object} item no detail64 : return {Object} no detail65 ‘‘‘javaScript66 var hiddenKey = this.hiddenKey;67 return item[hiddenKey];68 ‘‘‘6970 computeFilter71 : param {String} string no detail72 : return {null|Function} no detail73 ‘‘‘javascript74 var searchKey = this.searchKey;75 if (!string) {76 return null;77 } else {78 string = string.toLowerCase();79 return function(item) {80 var value = item[searchKey].toLowerCase();81 return (value.indexOf(string) != -1);82 };83 }84 ‘‘‘� �