Google JavaScript スタイルガイド - 日本語訳
JSDocコメント
最終更新:
aias-jsstyleguide2
-
view
JSDocコメント
我々はC++ style for commentsの考え方に従います。
全てのファイル、クラス、メソッド、プロパティにJSDocコメントが、適切なタグとデータ型を伴って記されるべきです。また名前から明白に判断できる場合を除き、プロパティ、メソッド、メソッドの引数、メソッドの戻り値を説明する文章が含まれているべきです。
インラインのコメントには//の方を使います。
完全文(Complete sentence)で書くことを推奨しますが、必須ではありません。完全文を使う場合は適切に大文字で開始し、句読点で終わらせましょう。
コメントの構文
JSDocの構文はJavaDocを元にしています。沢山のツールがJSDocコメントから取り出したメタデータを使ってコードの検証や最適化を行なっているため、コメントは適切に整形されたものでなければなりません。
JSDocのインデント
ブロックタグ内で改行が必要な場合、コードの改行と同様にスペース4つ分インデントしてください。
/**
* 長いparam/returnアノテーションの説明文の折り返し方を示します。
* @param {string} foo これは1行でおさめるには長すぎるパラメータの
* 説明文です。
* @return {number} この戻り値の説明文は長すぎて、とても1行の中には
* 入りきりません。
*/project.MyClass.prototype.method = function(foo) {
return 5;
};
@fileoverviewコマンドをインデントすべきではありません。@descコマンドはインデントしなくてかまいません。
推奨はしませんが、説明文の先頭で折り返しを揃える書き方も認めます。
/**
* これは決してお勧め'しない'インデントの方法です。
* @param {string} foo これは1行でおさめるには長すぎるパラメータの
* 説明文です。
* @return {number} この戻り値の説明文は長すぎて、とても1行の中には
* 入りきりません。
*/project.MyClass.prototype.method = function(foo) {
return 5;
};
JSDocの中のHTML
JavaDocと同じく、JSDocも多くのHTMLタグをサポートしています。<code>、<pre>、<tt>、<strong>、<ul>、<ol>、<li>、<a> 等々です。
これは、プレインテキストに書式を設定しても無視されることを意味します。このため、スペースによってJSDocを整形しようとしてはいけません:
/**
* 以下の3つの要因に基づいて重さを計算します:
* 送った項目
* 受け取った項目
* タイムスタンプ
*/
* 以下の3つの要因に基づいて重さを計算します:
* 送った項目
* 受け取った項目
* タイムスタンプ
*/
上のコメントは次のように表示されます。
以下の3つの要因に基づいて重さを計算します: 送った項目 受け取った項目 タイムスタンプ
代わりに、こうしてください:
/**
* 以下の3つの要因に基づいて重さを計算します:
* <ul>
* <li>送った項目
* <li>受け取った項目
* <li>タイムスタンプ
* </ul>
*/
JSDocコメントを適切な形式で書くには、JavaDocのスタイルガイドが役に立ちます。
トップ(ファイル)レベルのコメント
著作権表示と著作者情報は省略できます。ファイルが複数のクラス定義からなる場合には、一般的にファイル概要の記述が推奨されます。トップレベルのコメントは、そのファイルの中のコードに詳しくない読者をうまく導くように設計しましょう。そこにはファイルの全体的な説明、著者名、依存関係や互換性の情報が提供されているべきです。例を示します:
/**
* @fileoverview ファイルの説明、使い方や依存関係に
* ついての情報。
*/
クラスへのコメント
クラスへのコメントには、説明文とコンストラクタであることを示すタグを記述します。
/**
* 何だか楽しくなるクラス
* @param {string} arg1 もっと面白くする引数
* @param {Array.<number>} arg2 処理される数値のリスト
* @constructor
* @extends {goog.Disposable}
*/project.MyClass = function(arg1, arg2) {
// ...
};
goog.inherits(project.MyClass, goog.Disposable);
メソッドと関数へのコメント
パラメータと戻り値について記述されるべきです。メソッドのパラメータと戻り値が自明である場合には、説明を省略してもかまいません。メソッドの説明文は三人称の平叙文で書きます。
/**
* MyClass のインスタンスを操作し、何かを返します。
* @param {project.MyClass} obj 折り返して2行にしなければならないほど
* 長いコメントが続く、MyClass のインスタンス
* @return {boolean} 何かが起きたかどうか
*/function PR_someMethod(obj) {
// ...
}
プロパティへのコメント
/** @constructor */project.MyClass = function() {/**
* 枠の中に入れられる最大数。
* @type {number}
*/this.someProperty = 4;
}
JSDocタグリファレンス
タグ | 書式と例 | 説明 |
---|---|---|
@author |
@author メールアドレス (名 姓)
例: /**
* @fileoverview テキストエリアを扱うためのユーティリティ群。 * @author kuth@google.com (Uthur Pendragon) */ |
ファイルの著者、またはテストの所有者を記載します。通常@fileoverviewを含むコメントの中でのみ使用されます。 |
@code |
{@code ...}
例: /**
goog.dom.RangeIterator.prototype.next = function() {* 選択されたものの中で次の位置に移動します。 * Throws {@code goog.iter.StopIteration} 最後尾を * 超えた場合に発生する。 * @return {Node} 次の位置のノード。 */ // ... }; |
JSDocの説明文に含まれる語句がコードであることを示します。生成されたドキュメント内で適切に整形されることが想定されています。 |
@const |
@const
@const {型名} 例: /** @const */
var MY_BEER = 'stout';/**
mynamespace.MY_BEER = 'stout';* 名前空間が好きなビールの種類 * @const {string} */ /** @const */ MyClass.MY_BEER = 'stout'; /**
mynamespace.Request.prototype.initialize = function() {
* リクエストを初期化します。 * @const */ // サブクラスはこのメソッドをオーバーライドできません。
}; |
変数(またはプロパティ)が読み取り専用であることを示します。このタグはインラインで記述するのに向いています。 @constが付けられた変数はある値への固定された参照と見なされ、@const付きの変数やプロパティが上書きされているとCompilerは警告を出力します。 データ型を明確に推測できるのであれば型の宣言は省いてもかまいません。その他のコメントの追加も必須ではありません。 メソッドに@constが付けられている場合、そのメソッドに対しては単に上書きだけでなく、サブクラスによるオーバーライドも禁止されていることを意味します。 @constのより詳細な説明は「定数」を参照してください。 |
@constructor |
@constructor
例: /**
function GM_Rect() {* 長方形。 * @constructor */ ... } |
クラスの説明の中で使い、関数がコンストラクタであることを示します。 |
@define |
@define {型名} 説明文
例: /** @define {boolean} */
var TR_FLAGS_ENABLE_DEBUG = true;/**
goog.userAgent.ASSUME_IE = false;* @define {boolean} ブラウザがIEかどうかが * コンパイル時に設定される。 */ |
コンパイル時にCompilerによって上書きされる定数であることを示します。左の例でコンパイルフラグに--define='goog.userAgent.ASSUME_IE=true'と指定すると、ビルド後のファイルではgoog.userAgent.ASSUME_IEの値はtrueに置き換えられます。 |
@deprecated |
@deprecated 説明文
例: /**
BN_EditUtil.isTopEditableField = function(node) {* ノードがフィールドかどうかを判定します。 * @return {boolean} 要素の内容が * 編集可能ならtrue。ただし要素そのものは * 編集不可。 * @deprecated isField() を使ってください。 */ // ... }; |
関数、メソッド、プロパティをこれ以上使うべきでないことを伝えます。説明文の中でそれに替わるものを指示するのが普通です。 |
@dict |
@dict 説明文
例: /**
function Foo(x) {* @constructor * @dict */ this['x'] = x; } var obj = new Foo(123); var num = obj.x; // 警告 (/** @dict */ { x: 1 }).x = 123; // 警告 |
コンストラクタ(左の例のFoo)に@dictが付けられた場合、Fooオブジェクトのプロパティへのアクセスは角括弧による表記法でのみ可能となります。アノテーションをオブジェクトリテラルに直接記述することもできます。 |
@enum |
@enum {型名}
例: /**
project.TriState = {* 3つの状態を値にもつ列挙型。 * @enum {number} */ TRUE: 1, FALSE: -1, MAYBE: 0 }; |
|
@export |
@export
例: /** @export */
foo.MyPublicClass.prototype.myPublicMethod = function() {
// ...
}; |
--generate_exportsフラグを付けてコンパイルを実行すると、左のコードは次のように出力されます:
goog.exportSymbol('foo.MyPublicClass.prototype.myPublicMethod',
foo.MyPublicClass.prototype.myPublicMethod); コンパイル前のシンボルがエクスポートされているのが分かります。@exportを使用するには以下の条件のどちらかを満たしていなければなりません。 1. //javascript/closure/base.jsをインクルードしている 2. コードベース内にgoog.exportSymbolとgoog.exportPropertyの両方が同じメソッドシグネチャで存在している。 |
@expose |
@expose
例: /** @export */
MyClass.prototype.exposedProperty = 3; |
外部公開されているプロパティであることを宣言します。外部公開されたプロパティには削除、名前の変更、圧縮、Compilerによるいかなる最適化も実施されなくなります。同じ名前のプロパティを個別に最適化することはできません。 ライブラリのコードに対しては@exposeを使用すべきではありません。今まで正常に行われていたプロパティの削除を妨げることになるからです。 |
@extends |
@extends 型名
@extends {型名} 例: /**
goog.ds.EmptyNodeList = function() {* 常に空のノードリスト * @constructor * @extends goog.ds.BasicNodeList */ ... }; |
@constructorと共に使用し、あるクラスが別のクラスを継承していることを示します。型を囲む波括弧は省略可能です。 |
@externs |
@externs
例: /**
* @fileoverview これはexternファイルです。 * @externs */ var document; |
externファイルであることを宣言します。 |
@fileoverview |
@fileoverview 説明文
例: /**
* @fileoverview 何かをするユーティリティ群。その説明には * このように長くてインデントされていないコメントを必要とします。 * @author kuth@google.com (Uthur Pendragon) */ |
ファイルレベルの情報を提供するコメントブロックを構成します。 |
@implements |
@implements 型名
@implements {型名} 例: /**
function Shape() {};* 形状。 * @interface */ Shape.prototype.draw = function() {}; /**
function Square() {};* @constructor * @implements {Shape} */ Square.prototype.draw = function() { ... }; |
@constructorと共に使用し、あるクラスがインタフェースを実装していることを示します。型を囲む波括弧は省略可能です。 |
@inheritDoc |
@inheritDoc
例: /**
project.SubClass.prototype.toString() {* @inheritDoc */ // ... }; |
非推奨。@overrideを使ってください。
サブクラスのメソッド・プロパティが、スーパークラスのメソッド・プロパティを意図的に隠蔽しており、全く同じJSDocコメントを持つことを示します。@inheritDocは@overrideを包含する点に注意してください。 |
@interface |
@interface
例: /**
function Shape() {};* 形状。 * @interface */ Shape.prototype.draw = function() {}; /**
function Polygon() {};* 多角形。 * @interface * @extends {Shape} */ Polygon.prototype.getSides = function() {}; |
その関数がインタフェースであることを示すために使います。 |
@lends |
@lends オブジェクト名
@lends {オブジェクト名} 例: goog.object.extend(
Button.prototype, /** @lends {Button.prototype} */ { isButton: function() { return true; } }); |
オブジェクトリテラルのキーが他のオブジェクトのプロパティとして扱われるべきであることを示します。このアノテーションはオブジェクトリテラルにだけ付けられます。 他のアノテーションとは異なり、波括弧の中の名前はクラス名ではなくオブジェクト名である点に注意してください。それはプロパティが "lent"(貸与)されているオブジェクトの名前です。例えば@type {Foo} は "Fooのインスタンス" を意味しますが、@lends {Foo} は "Fooのコンストラクタ関数" のことです。 このアノテーションについてのより詳しい説明はJSDoc Toolkit のドキュメント(日本語)を参照してください。 |
@license or @preserve |
@license 説明文
例: /**
* @preserve Copyright 2009 SomeThirdParty. * このファイルに関する完全なライセンス条項と * 著作権表示を記載します。文章は複数行にわたっても構いませんが、 * 必ず末尾は "*/" で閉じられている必要があります。 */ |
@licenseまたは@preserveが付けられたコメントはCompilerの処理から保護され、コンパイルされたコードよりも前に出力されます。コンパイルの影響を受けないことから、このアノテーションは重要な通知(ライセンスや著作権のような)を行うのに向いています。改行もそのまま残されます。 |
@noalias |
@noalias
例: /** @noalias */
function Range() {} |
Externファイルの中で使い、この変数または関数に別名を付けてはならないことをCompilerに示します。 |
@nocompile |
@nocompile
例: /** @nocompile */
// JavaScriptコード
|
ファイルの先頭に記述し、このファイルのコードをパースするだけでコンパイルしないようコンパイラへ伝えます。このアノテーションは、コンパイルが意図されていない、またはコンパイルテストから除外すべきコード(例えば、ブートストラップコード)に対して使用します。控えめに使ってください。 |
@nosideeffects |
@nosideeffects
例: /** @nosideeffects */
function noSideEffectsFn1() {
// ...
};/** @nosideeffects */
var noSideEffectsFn2 = function() {
// ...
};/** @nosideeffects */
a.prototype.noSideEffectsFn3 = function() {
// ...
}; |
関数やコンストラクタに付けられ、それらの呼び出しが他のコードに影響を及ぼさないことを示します。このアノテーションはCompilerに対し、戻り値が使用されていない場合にそれらの関数を削除することを許可します。 |
@override |
@override
例: /**
project.SubClass.prototype.toString = function() {* @return {string} project.SubClassの人間が理解できる表現。 * @override */ // ... }; |
サブクラスのメソッド・プロパティが、スーパークラスのメソッド・プロパティを意図的に隠蔽していることを示します。コメントにこれ以外の記述が含まれない場合、スーパークラスで書かれた内容がサブクラスに引き継がれます。 |
@param |
@param {型名} 変数名 説明文
例: /**
goog.Baz.prototype.query = function(groupNum, term) {* 各項目のBazを問い合わせます。 * @param {number} groupNum 問い合わせのためのサブグループID。 * @param {string|number|null} term 項目名、 * または項目ID、もしnullの場合は全て検索します。 */ // ... }; |
メソッド、関数、コンストラクタに対し、それらの引数を説明するために使用します。 型名は必ず波括弧で括られていなければなりません。型名が省略された場合、Compilerは型チェックを行いません。 |
@private |
@private
@private {型名} 例: /**
this.handlers_ = [];* このロガーを監視しているハンドラの配列。 * @private {!Array.<Function>} */ |
メソッド・プロパティ名の末尾にアンダースコアを付加する仕様と組み合わせて、メンバがprivateであり、オーバーライドできないことを示します。 |
@protected |
@protected
@protected {型名} 例: /**
goog.ui.Component.prototype.setElementInternal = function(element) {* 指定されたDOM要素をコンポーネントのルート要素として設定します。 * @param {Element} element コンポーネントのルート要素 * @protected */ // ... }; |
メソッド・プロパティがprotectedであることを示します。名前の末尾にアンダースコアを付けてはいけません。 |
@public |
@public
@public {型名} 例: /**
goog.events.Event.prototype.propagationStopped_ = false;* イベント内部のキャプチャ/バブリング処理をキャンセルするかどうか * @public {boolean} * @suppress {visibility} これをこのパッケージの外部から参照すべき * ではありません。 */ |
メソッド・プロパティがpublicであることを示します。変数やプロパティはデフォルトでpublicなので、このアノテーションはめったに必要とされません。古いコードの中で、privateを表す名前を簡単に書き換えられないときにだけ使用してください。 |
@return |
@return {型名} 説明文
例: /**
goog.Baz.prototype.getLastId = function() {* @return {string} 最後の項目の16進数表記のID */ // ... return id; }; |
メソッドと関数に対し、それらの戻り値を説明するために使用します。論理型の戻り値の説明では、"コンポーネントが見えるならtrue、そうでなければfalse" よりも "コンポーネントが見えるかどうか" の方が良い書き方です。戻り値が無い場合、@returnタグは使わないで下さい。 型名は必ず波括弧で括られていなければなりません。型名が省略された場合、Compilerは型チェックを行いません。 |
@see |
@see リンク
例: /**
...* むやみに項目を追加します。 * @see #addSafely * @see goog.Collect * @see goog.RecklessAdder#add |
他のクラス、関数、メソッドへの参照を記載します。 |
@struct |
@struct 説明文
例: /**
function Foo(x) {* @constructor * @struct */ this.x = x; } var obj = new Foo(123); var num = obj['x']; // 警告 obj.y = "asdf"; // 警告 Foo.prototype = /** @struct */ { method1: function() {} }; Foo.prototype.method2 = function() {}; // 警告 |
コンストラクタ(左の例のFoo)に@structが付けられた場合、Fooオブジェクトのプロパティへのアクセスはドットによる表記法でのみ可能となります。また、生成されたFooオブジェクトへ新しいプロパティを追加することはできません。アノテーションをオブジェクトリテラルに直接記述することもできます。 |
@supported |
@supported 説明文
例: /**
* @fileoverview イベントマネージャ * ブラウザ固有のイベントシステムを抽象化した * インタフェースを提供します。 * @supported これまで IE6 と FF1.5 でテスト済みです。 */ |
@fileoverviewを含むコメントブロックで使用し、このファイルの内容をサポートするブラウザを記載します。 |
@suppress |
@suppress {警告1|警告2}
@suppress {警告1,警告2} 例: /**
function f() {* @suppress {deprecated} */ deprecatedVersionOfF(); } |
ツールからの警告を抑止します。警告の種類が複数ある場合は|か,で区切ります。 |
@template |
@template
例: /**
goog.bind = function(fn, thisObj, var_args) {* @param {function(this:T, ...)} fn * @param {T} thisObj * @param {...*} var_args * @template T */ ... }; |
このアノテーションはテンプレート型を宣言するために使用します。 |
@this |
@this 型名
@this {型名} 例: pinto.chat.RosterWidget.extern('getRosterElement',
/**
function() {* 名簿ウィジェットの要素を返します。 * @this pinto.chat.RosterWidget * @return {Element} */ return this.getWrappedComponent_().getElement(); }); |
特定のメソッドが呼ばれるときのコンテキストの型を表します。thisがプロトタイプメソッドでない関数から参照されているときに必要です。 |
@type |
@type 型名
@type {型名} 例: /**
var hexId = hexId;* 16進数形式のID。 * @type {string} */ |
変数、プロパティ、式のデータ型を表します。ほとんどの型において波括弧で囲むことは必須ではありませんが、一貫性のためにそれを強制しているプロジェクトもあります。 |
@typedef |
@typedef
例: /** @typedef {(string|number)}
*/
goog.NumberLike;/** @param {goog.NumberLike} x
数値か文字列 */
goog.readNumber = function(x) {... } |
このアノテーションは複雑な型に別名を付けるために使用します。 |
サードパーティのコードの中で、上記以外の種類のJSDocアノテーションが使われているのを目にするかもしれません。それらはJSDoc Toolkitタグリファレンスに現れるものですが、Googleのコーディングルールでは今のところ使用を推奨しません。以下のアノテーションは将来の利用に備えて「予約されている」名前だと考えてください:
- @augments
- @argument
- @borrows
- @class
- @constant
- @constructs
- @default
- @event
- @example
- @field
- @function
- @ignore
- @inner
- @link
- @memberOf
- @name
- @namespace
- @property
- @public
- @requires
- @returns
- @since
- @static
- @version
* JSDocコメントはスラッシュと2つのアスタリスクから始めます。
* インラインタグは {@code this} のように波括弧で囲みます。
* @desc ブロックタグは必ず行の先頭から開始します。
*/