はじめに HTML5 の登場 Web 上で可能な表現や操作の増加開発まわりも大きく変化 2

Size: px

Start display at page:

Download "はじめに HTML5 の登場 Web 上で可能な表現や操作の増加開発まわりも大きく変化 2"

あおいかやぬま
5 years ago
Views:

1 Web Components 開発におけるドキュメント同時生成手法の提案 1

2 はじめに HTML5 の登場 Web 上で可能な表現や操作の増加開発まわりも大きく変化 2

3 はじめにソフトウェア開発手法の輸入データバインディング MVVM(Model/View/ViewModel) モデルタスクランナー Grunt/Gulp.js ECMAScript2015 etc 3

4 Web Components Web ページの構成要素をコンポーネント化 Web 標準の技術となる予定 3 つの仕様で構成 Shadow DOM Custom Elements HTML Imports Google Chrome や Polyfill ライブラリの使用で利用することが可能 4

5 Web Components 利点独自タグの定義および使用必要なリソースの一括ロードコンポーネントの利用の簡単化マークアップ構造スタイルのカプセル化競合問題とそれに対する対策コストの削減 ID の重複 ( クラスの重複による ) デザイン指定の競合 5

6 Web Components 例 Twitter の Like ボタン 6

7 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

8 Web Components 例 Twitter の Like ボタン Web Components 化で例えば次のような簡潔な記述で使いまわせるように <twitter-like-button animate liked value="13203"> </twitter-like-button> 8

9 Web Components 実体 1 つの HTML ファイルとして提供コンポーネント化部分のマークアップマークアップに対するデザイン指定 (CSS) 動作や API などの定義 (JavaScript) 9

10 Web Components 実体 <template> <style>/* デザイン指定 */</style>  </template> <script> var proto = Object.create( ); // 動作 API の定義 var Tag = document.registerelement( "tag-name", {prototype: proto}); </script> 10

11 問題点ユーザ向けの (API) ドキュメントの作成現状ドキュメント単体を個別に作成するかコードそのものをドキュメントとしている従来から使われている手法が使えないドキュメントコメント文芸的プログラミング 11

12 従来手法ドキュメントコメントコード中に記述した特殊なコメントを解析しドキュメントを生成する方法 Java における JavaDoc など広く活用される /** * メソッドの説明 arg 引数の説明戻り値の説明 */ public int funcname(int arg){ } 12

13 従来手法ドキュメントコメント正規化されたドキュメントを作成可能元来単一の言語のコードに対して使われる複数の言語が混在している状況では使えない API に対する記述以外の内容はどこに載せるのが適当かライセンスや制作者など 13

14 従来手法文芸的プログラミング Knuth が提唱するプログラミングスタイルコード断片 14

15 従来手法文芸的プログラミング複数の言語の存在するコードでも対応可能出力されるドキュメントの形式がユーザ向けのドキュメントではないドキュメントコメント方式と比較してより書き方に依存するドキュメントが生成される 15

16 目的 1 つの記述で 1 つの Web Components のコードとドキュメントを同時生成これを行うツールの作成有用性の検証 16

17 着眼点ドキュメントコメント書き方がある程度決まっている一定の内容の出力を保証文芸的プログラミング複数の言語が混在していても問題ない自由度の高い記述が可能両者の強みを活かす 17

18 提案手法ドキュメントのなかにコードを埋め込む埋め込まれたコードとドキュメントの内容を合わせて 1 つの完成したコードを生成コードなどの不要な部分の除去を行った上ユーザドキュメントを生成する 18

19 提案手法記述例 ## 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

20 提案手法記述例 ## properties propertyname1 : `"initial value"` : type String Explanation of propertyname1 propertyname2 : type Number : ` `... 20

21 提案手法記述例 ## 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 提案手法概念図ドキュメントのなかにコードを埋め込む 22

23 提案手法概念図埋め込まれたコードとドキュメントの内容を合わせて 1 つの完成したコードを生成 23

24 提案手法概念図コードなどの不要な部分の除去を行った上ユーザドキュメントを生成する 24

25 ドキュメント記法ドキュメントをどの記法で記述するか以下のような条件を満たすべき記述が容易素の状態で読みやすい最低限の文書構造を記述可能プログラムコードの埋め込みが可能可能ならばよく知られた汎用的な記法 25

26 Markdown 記法 Gruber が提唱する簡易マークアップ言語テキストメールの装飾に似た記法 Web を中心に広く活用されてる GitHub でのドキュメント (ReadMe) ブログの記事の編集 WordPress/Octopress/ はてなブログ 26

27 Markdown 記法 # 見出しレベル 1 ## 見出しレベル 2 空行までが 1 段落になる _ 強調 _ などの ** テキスト装飾 ** も行える ```javascript console.log(" プログラムコードも埋め込み可 ") ``` - リスト記法なども - 用意されている 27

28 書式レベル 1 の見出しをタグ名としてタイトル代わりに使用する見出しから見出しまでをセクションとしてレベル 2 のセクションに各種定義をしていく # tag-name ## section title section contents ## section title section contents 28

29 書式マークアップスタイルマークアップはstructureセクションスタイル指定はstyleセクションセクション中のコードを抽出して利用その他の内容は使用しない 29

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> 30

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> 31

32 書式マークアップスタイル ## 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

33 書式プロパティ定義 properties セクションで定義定義リスト記法で定義用語をプロパティ名とする定義には型や初期値などを指定次に定義リストが現れるまでの内容は前の定義リストのプロパティに対する説明 33

34 書式プロパティ定義 ## properties propertyname1 : `"initial value"` : type String 1 つのプロパティの定義 Explanation of propertyname1 propertyname2 : type Number : ` `... 34

35 書式プロパティ定義 ## properties propertyname1 : `"initial value"` : type String プロパティ名 Explanation of propertyname1 propertyname2 : type Number : ` `... 35

36 書式プロパティ定義 ## properties propertyname1 : `"initial value"` : type String 初期値 Explanation of propertyname1 propertyname2 : type Number : ` `... 36

37 書式プロパティ定義 ## properties propertyname1 : `"initial value"` : type String 型名 Explanation of propertyname1 propertyname2 : type Number : ` `... 37

38 書式プロパティ定義 ## properties propertyname1 : `"initial value"` : type String Explanation of propertyname1 説明 propertyname2 : type Number : ` `... 38

39 書式メソッド定義 methods セクションで定義プロパティ同様定義リスト記法で定義次に定義リストが現れるまでの内容のうちで最後に現れるコードを処理内容とする 39

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); 40

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); 41

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); 42

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); 43

44 書式メソッド定義 ## 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

45 書式メタ情報の記述 YAML Front Matter で記述広く使われている手法著者情報や依存関係の記述に使用後述のツールの動作指定にも利用 45

46 書式その他の記述以下について定義可能ライフサイクルコールバックテストコードデモコード具体的な記法は想定していないがその他自由に内容を記述することが可能 46

47 実装 Node.js 上で動作する CLI として実装 Polyfill ライブラリ (Polymer) の使用を想定したコードを出力する HTML 形式の API ドキュメントを出力 github.com/e8l/wcweb 47

48 実装動作フロー 1. YAML Front Matterの解析 2. Markdownの解析 AST 作成 3. コードの抽出内容の解析 4. コードの生成 5. ASTの整形 6. ドキュメントの出力 48

49 実装 AST 作成 Pandoc を用いて JSON 形式の AST を取得さらに DOM に似せたデータ構造へ変換解析や整形を行いやすくするため 49

50 実装コード生成テンプレートエンジンを用いて作成 Mustache というエンジンを使用ひな形とドキュメントの記述から外枠を作り抽出したコード片と組み合わせる 50

51 実装 AST 整形ドキュメント出力 API ドキュメントとして不必要な内容を除去実装に用いるコードやテストコード更新履歴やインストール方法整形後の AST を JSON 形式に逆変換して Pandoc を用いてドキュメントを出力更新履歴などは ReadMe テキストへ出力 51

52 実装外部ツール連携 YAML Front Matter 部でタスクを指定 Lint や難読化などを別ツールを用いて実行代替言語を用いた作成 HTML や CSS は代わりに Haml や SCSS などを使用して記述可能オプションで CoffeeScript を使用することも可能 52

53 考察仕様策定段階にあることについてあまりにも大きな変更は恐らくない HTML CSS JavaScript を同時に扱うならば出力形式変更で対処可能 53

54 考察対象の拡大について手法自体は文芸的プログラミングと同様に言語によらず使用可能ドキュメント駆動開発や Readme 駆動開発との親和性が高い 54

55 考察エディタのサポートいくつかのエディタはシンタックスハイライト可 55

56 VIM 56

57 Atom 57

58 考察エディタのサポートいくつかのエディタはシンタックスハイライト可コードの補完やインテリセンスは未サポート専用エディタやプラグインを新たに用意する必要 58

59 考察 Markdown によるドキュメントの記述ドキュメントの記述性を阻害する可能性文書構造に意味をもたせているため独自記法の導入か用いる文書構造の調整が必要になる可能性がある 59

60 今後の展望定量的定性的な有用性の検証提案手法の応用分野の検討 Web Components 以外の作成に使用可能か教育などへの利用ができないか 60

61 関連研究 Web Components Cascading Tree Sheet[2][3] Benson らが提唱するコンポーネント化手法 CSS に似た構文で記述 SmartComposition[5] Web Components を用いた研究マルチデバイス向けのマッシュアップライクな Web アプリケーション作成を容易に 61

62 関連研究 Markdown Madoko[7] 複雑なドキュメントのためのオーサリングツール RUMU Editor[8] フレームワークを用いて Web ページを作成 API Blueprint WebAPI の記述とドキュメント作成 62

V8.1新規機能紹介記事

V8.1新規機能紹介記事 WebOTX V8.1 新規機能 EJB 3.0 WebOTX V8.1より Java EE 5(Java Platform, Enterprise Edition 5) に対応しましたこれによりいろいろな機能追加が行われていますが特に大きな変更であるEJB 3.0 対応についてご紹介いたしますなお WebOTX V7で対応したEJB 2.1についてもWebOTX V8.1で引き続き利用することが可能です

はじめに HTML5 の登場 Web 上で可能な表現や操作の増加 開発まわりも大きく変化 2

はじめに HTML5 の登場 Web 上で可能な表現や操作の増加開発まわりも大きく変化 2