Closure Library のすべてのコードにはドキュメントが付属しています。
下のコードを見てください。このコードは goog.array の一部分を翻訳したものです。
/** * 配列が空かどうかを判定する。 * @param {goog.array.ArrayLike} arr 判定したい配列。 * @return {boolean} 空であれば true 。 */ goog.array.isEmpty = function(arr) { return arr.length == 0; };
/** ... */ で囲まれた部分はコメントです。なにやら一定の規則に従って記述されているように見えますね。
実は、このコメントをつかって自動的に API ドキュメントを生成することができます。
このコメントはアノテーション（注釈）と呼ばれていて、次の規則で記述されています。
オブジェクトの説明
メソッドの引数の説明
@param {引数の型} 引数の名前 引数の説明
メソッドの戻り値の説明
@return {戻り値の型}
説明対象のオブジェクト
このようにプログラムと一体化しているドキュメントには2つのメリットがあります。
コーディングしながらドキュメントを書ける
ドキュメントの保守性が向上する
Closure Linter と Closure Compiler でエラーチェックができるようになる
スクリプトを書きあげてから、「さあドキュメントを書くぞ！」ってなると最初の方の仕様を忘れてたりしませんか？
コーディングしながらドキュメントを書くとそんなことはなくなります。
また、ドキュメントを書いていると設計の不備・不味さに気づくことが少なからずあります。
たとえば、ドキュメントを書いていくと「このクラス（メソッド）は一体何をしているのかよく説明できない」ということがあります。
こういうときは、だいたいクラス・メソッドがよく分割されていない（＝機能的凝集度が低い）状態のときです。
ここではアノテーションだけでなくソースコードもドキュメントに利用している、というところが重要です。
たとえば、アプリケーションを開発しているときに名前空間の重複が発覚したとしましょう。
こういう場合は、名前空間を別の名前にして重複を回避することになります。
したがって、この場合は名前空間のメンバ名をすべて書き換える必要がありますね。
ドキュメントを Excel や Google Doc で管理している場合には、ソースコードとドキュメントの双方を書き換えなければなりません。
しかし、このソースコード埋め込み型のドキュメントはソースコードの内容からオブジェクトの名前を取得しているため、ソースコードの書き換えだけで済むのです。
ここで記述したアノテーションは JsDoc などのドキュメント生成ツールによって html へと出力することができます。
とくに JsDoc3 が Closure Library と相性が良いように思います。こちらについては姉妹 wiki のこちらで解説しています。
Closure Library のアノテーションは JSDoc アノテーションに似ていますが、部分的に違いがあります。
そこで、この wiki ではこれらを区別して Closure Library のアノテーションを Closure アノテーションと呼んでいます。
さて、モジュールのソースコードに Closure アノテーションを追加してみましょう。
// このモジュールはパブリックライセンス！ /** * @fileoverview ほげほげなモジュール。 * @author あなたのメールアドレス (あなたの名前) */ goog.provide('hogehoge.Hoge'); /** * ほげほげなクラス。 * @constructor */ hogehoge.Hoge = function() { this.msg_ = null; // <- 'Hoge!' がセットされていないといけない！ }; /** * メッセージを取得する。 * @return {string} メッセージ。 */ hogehoge.Hoge.prototype.get = function() { return this.msg_; }; /** * メッセージを設定する。 * @param {string} msg 設定したいメッセージ。 */ hogehoge.Hoge.prototype.set = function(msg) { this.msg_ = msg; };
Closure アノテーションの書き方については Closure アノテーションの記述方法 を参照してください。
Closure Linter というツールは”まずい習慣”やコードとドキュメントとの整合性ミスを指摘してくれます。
たとえば、悪名高い == 演算子※がスクリプトに含まれていると「=== に直せ！」と指摘されます。
まずい習慣については Google JavaScript Style Guideline (和訳) に記載されています。
※ == 演算子は undefined == null や null == 'null' が真になるという不可解な挙動を示します。undefined === null はちゃんと偽になるのでよくわからない場合は === 演算子を使うべきです。