• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

「JavaScript ドキュメント規約」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
([)
(ja.wordpress.org へ移動)
 
1行目: 1行目:
<p class="important">注意: この記事は「[https://make.wordpress.org/core/handbook/ Core Contributor Handbook]」の「[https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/ JavaScript Documentation Standards]」(2016年8月15日時点)の訳です。<br />最新版については[https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/ 英語版]を参照してください。</p>
+
このページは https://ja.wordpress.org/team/handbook/coding-standards/inline-documentation-standards/javascript/ へ移動しました。
 
+
WordPress はインライン JavaScript ドキュメントの規約として「[http://usejsdoc.org/ JSDoc 3 Standard]」に遵守します。
+
 
+
参照: [[WordPress コーディング規約]]、[[WordPress インラインドキュメント規約]]
+
 
+
== 何をドキュメントするか<span id="What_Should_Be_Documented"></span> ==
+
 
+
WordPress での JavaScript ドキュメントの形態は、フォーマットされたドキュメントブロックか、インラインコメントになります。
+
 
+
以下のリストは WordPress JavaScript ファイルでドキュメントする項目の例です。
+
 
+
* 関数、およびクラスのメソッド
+
* オブジェクト
+
* クロージャ
+
* オブジェクトプロパティ
+
* require
+
* イベント
+
* ファイルヘッダー
+
 
+
== ドキュメントのヒント<span id="Documenting_Tips"></span> ==
+
 
+
=== 文体<span id="Language"></span> ===
+
 
+
短い説明を書く場合には、明確でシンプルな、短い文を心がけてください。「いつ」「何を」実行するのかをドキュメントしてください。「なぜ」を含める必要性はほとんどないはずです。
+
 
+
関数やクロージャは「三人称単数」の要素です。説明を記述する場合も「三人称単数の動詞」を使用してください。
+
 
+
<p class="important">ヒント: 三人称単数の動詞の活用に悩む場合は、関数やクロージャの説明を書く場合、先頭に「It」をつけて考えてください。<br />
+
- ''正'': "(It) Does something."<br />
+
- ''誤'': "(It) Do something."
+
</p>
+
 
+
* '''関数''': この関数は「何を」するのか?
+
** 正: ''Handles a click on X element.'' (要素「X」のクリックを処理する)
+
** 誤: ''Included for back-compat for X element.'' (要素「X」の後方互換性のために追加された)
+
 
+
@since: WordPress に追加されたバージョン番号等を調べるには「[http://make.wordpress.org/core/handbook/svn/code-history/#using-subversion-annotate svn blame]」の使用を推奨します。
+
 
+
バージョン番号を特定できない場合は、「<tt>@since Unknown</tt>」を使用してください。
+
 
+
'''コードリファクタリング''': ドキュメントを編集する際に、ファイル内のコードはリファクタリングしないでください。
+
 
+
=== 文法<span id="Grammar"></span> ===
+
 
+
説明文の要素は完全な文として記述してください。例外はファイルヘッダーの Summary です。この Summary は文章ではなく「タイトル」を意図しているためです。
+
 
+
Summary、Description、Parameter や Return の Description 内で要素を並べる際には serial comma (Oxford comma) を使用してください。(例: A, B and C)
+
 
+
== フォーマットガイドライン<span id="Formatting_Guidelines"></span> ==
+
 
+
次のガイドラインに従うことで DocBlock の内容はコードリファレンス用に正しくパースされます。
+
 
+
'''短い説明''':
+
 
+
短い説明は単一の文で書き、マークアップしないでください。説明が HTML 要素やタグを参照する場合は「link タグ」のように記述してください。例: "Fires when printing the link tag in the header"。
+
 
+
'''長い説明''':
+
 
+
長い説明では必要であればマークダウンを使用できます。
+
 
+
'''@param および @return タグ''':
+
 
+
これらのタグの説明では HTML もマークダウンも許されません。HTML 要素やタグは「audio 要素」や「link タグ」のように記述してください。
+
 
+
=== 行の折り返し<span id="Line_wrapping"></span> ===
+
 
+
DocBlock のテキストは80文字分で次の行に折り返してください。例えば DocBlock が20文字分インデントしている場合には、100文字目の位置で折り返します。ただし120文字目以上は超えないでください。
+
 
+
 
+
== 関数<span id="Functions"></span> ==
+
 
+
関数は次のようにフォーマットしてください。
+
 
+
* @summary: 関数の目的を説明する簡潔な単一の文。最大でも2行。最後はピリオド。
+
* '''長い説明''': Summary を補足する詳細な説明。文の最後はピリオド。
+
* @deprecated '''x.x.x''': 非推奨になった関数のみに使用する。どの WordPress バージョンで非推奨になったかを示す常に3組の数字 (例 @deprecated 3.6.0) と代替の関数。
+
* @since '''x.x.x''': 常に3組の数字 (例: @since 3.6.0)
+
* @access: 関数が private の場合のみ使用。内部使用専用となり、コードリファレンスにドキュメントされない。
+
* @class: クラスのコンストラクタに使用
+
* @augments: クラスのコンストラクタで、クラスの継承チェーンを直近の親クラスから先祖へリストする。
+
* @mixes: オブジェクトにミックスされる mixin をリストする。
+
* @static: クラスに対し、クラスコンストラクタで関数が static メソッドであることを示す。
+
* @see: 依存する関数やクラス
+
* @link: 詳細情報への URL
+
* @fires: 関数から呼ばれるイベント
+
* @listens: この関数が期待するイベント
+
* @global: 関数内で使用される JavaScript グローバル変数。オプションで変数を説明する。
+
* @param: 変数の簡単な説明。JSDoc @param 構文を使用して、変数がオプションかどうかや、デフォルト値等を示す。
+
* @return: 注意: 説明の最後はピリオド
+
 
+
<pre>
+
/**
+
* @summary Short description. (ピリオドを使用)
+
*
+
* Long. (ピリオドを使用)
+
*
+
* @since x.x.x
+
* @deprecated x.x.x Use new_function_name() を使用。
+
* @access private
+
*
+
* @class
+
* @augments superclass
+
* @mixes mixin
+
*
+
* @see Function/class relied on
+
* @link URL
+
* @global type $varname Short description.
+
* @fires target:event
+
* @listens target:event
+
*
+
* @param type $var Description.
+
* @param type $var Optional. Description.
+
* @return type Description.
+
*/
+
</pre>
+
 
+
== オブジェクトプロパティ<span id="Object_Properties"></span> ==
+
 
+
オブジェクトプロパティは次のようにフォーマットしてください。
+
 
+
* 短い説明: 最後はピリオド
+
* @since '''x.x.x''': 常に3組の数字(例 <tt>@since 3.6.0</tt>)
+
* @access: 「private」「protected」「public」のどれか。private プロパティは内部使用のみを意味する
+
* @property: <tt>@param</tt> と同様の形式
+
 
+
<pre>
+
/**
+
* Short description. (ピリオドを使用)
+
*
+
* @since x.x.x
+
* @access (private、protected または public)
+
* @property type $var Description.
+
*/
+
</pre>
+
 
+
== インラインコメント<span id="Inline_Comments"></span> ==
+
 
+
メソッドや関数のインラインコメントは次のようにフォーマットしてください。
+
 
+
=== 単一行コメント<span id="Single_line_comments"></span> ===
+
 
+
<pre>
+
// Extract the array values.
+
</pre>
+
 
+
=== 複数行コメント<span id="Multi-line_comments"></span> ===
+
   
+
<pre>
+
/*
+
* This is a comment that is long enough to warrant being stretched over
+
* the span of multiple lines. You'll notice this follows basically
+
* the same format as the JSDoc wrapping and comment block style.
+
*/
+
</pre>
+
 
+
== ファイルヘッダー<span id="File_Headers"></span> ==
+
 
+
JSDoc ファイルヘッダーブロックにはファイルに含まれる内容の概要を書きます。
+
 
+
可能であれば常にすべての WordPress JavaScript ファイルにヘッダーブロックを記述してください。
+
 
+
必要とされるファイルやライブラリについても @requires タグを使用して短い説明の JSDoc ブロックでドキュメントしてください。
+
 
+
WordPress は JSHint を使用して全般的なコードの品質を検証します。インライン構成オプションはヘッダーブロックの最後に記述してください。
+
 
+
<pre>
+
/**
+
* (ファイルの目的を書いた長い説明をここに書く。
+
* ファイル内のすべての機能を詳細に記述する。
+
* 説明は複数行にわたっても構わない。最後はピリオドで終わること)
+
*
+
* @summary  ファイルの短い説明。
+
*
+
* @link  URL
+
* @since x.x.x (もしあれば)
+
* @requires javascriptlibrary.js
+
* @class
+
* @classdesc This is a description of the MyClass class.
+
*/
+
+
/** jshint {ここにインライン構成} */
+
</pre>
+
 
+
== サポートされる JSDoc タグ<span id="Supported_JSDoc_Tags"></span> ==
+
 
+
<table style="border-width: thin; border-style: solid; border-collapse: collapse;">
+
<tr style="border-bottom: thin solid black;">
+
<th>タグ</th>
+
<th>説明</th>
+
</tr>
+
<tr style="border-bottom: thin solid black;">
+
<td>@abstract</td>
+
<td>このメソッドは継承側から実装、またはオーバーライドできる。</td>
+
</tr>
+
<tr style="border-bottom: thin solid black;"><td>access</td><td>このメンバーのアクセスレベルを指定する (private、public、protected)</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@alias</td><td>メンバーに別名があるものとして扱う。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@augments</td><td>このクラスは親クラスから継承する。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@author</td><td>項目の作者を識別</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@borrows</td><td>このオブジェクトは別のオブジェクトの何かを使用する。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@callback</td><td>コールバック関数をドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@class</td><td>この関数はクラスのコンストラクター</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@classdesc</td><td>クラス全体の記述に次のテキストを使用する。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@constant</td><td>オブジェクトを定数としてドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@constructs</td><td>この関数メンバーは前のクラスのコンストラクターになる。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@copyright</td><td>著作権情報をドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@default</td><td>デフォルト値をドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@deprecated</td><td>非推奨の機能であることをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@description</td><td>シンボルについて記述</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@enum</td><td>関連するプロパティのコレクションをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@event</td><td>イベントをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@example</td><td>ドキュメントされた項目の使用例を提示</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@exports</td><td>JavaScript モジュールからエクスポートされるメンバーを識別</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@external</td><td>外部クラス、名前空間、モジュールをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@file</td><td>ファイルについて記述</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@fires</td><td>このメソッドが呼び出すイベントを説明する。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@function</td><td>関数、またはメソッドについて記述</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@global</td><td>グローバルオブジェクトをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@ignore</td><td>[todo] 最終出力かこれをら除去</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@inner</td><td>内部オブジェクトをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@instance</td><td>インスタンスメンバーをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@kind</td><td>このシンボルの種類は何か?</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@lends</td><td>与えられた名前のシンボルに属すようにオブジェクトリテラルのプロパティをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@license</td><td>[todo] このコードに適用されるソフトウエアライセンスをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@link</td><td>インラインタグ - リンクを作成</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@member</td><td>メンバーをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@memberof</td><td>このシンボルは親のシンボルに属す。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@mixes</td><td>このオブジェクトは他のオブジェクトのすべてのメンバーを mixin する。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@mixin</td><td> mixin オブジェクトをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@module</td><td>JavaScript モジュールをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@name</td><td>オブジェクトの名前をドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@namespace</td><td>名前空間オブジェクトをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@param</td><td>関数へのパラメータをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@private</td><td>このシンボルは private</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@property</td><td>オブジェクトのプラパティをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@protected</td><td>メンバーは protected</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@public</td><td>このシンボルは public</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@readonly</td><td>このシンボルはリードオンリー</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@requires</td><td>このファイルは JavaScript モジュールが必要</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@returns</td><td>関数の戻り値をドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@see</td><td>詳細については他のドキュメントを参照</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@since</td><td>いつ、この機能は追加されたか?</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@static</td><td>静的メンバーをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@summary</td><td>完全な説明の短い版</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@this</td><td>'this' キーワードはここで何を参照するか?</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@throws</td><td>どんなエラーがスローされるかを記述</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@todo</td><td>完了すべきタスクをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@tutorial</td><td>同梱されるチュートリアルファイルへのリンクを挿入</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@type</td><td>オブジェクトの型をドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@typedef</td><td>カスタムタイプをドキュメント</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@variation</td><td>同一名で異なるオブジェクトを区別</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@version</td><td>アイテムのバージョン番号をドキュメント</td></tr>
+
</table>
+
 
+
== サポートされない JSDoc タグ<span id="Unsupported_JSDoc_Tags"></span> ==
+
 
+
<table style="border-width: thin; border-style: solid; border-collapse: collapse;">
+
<tr style="border-bottom: thin solid black;">
+
<th>タグ</th>
+
<th>なぜサポートされないか</th>
+
</tr>
+
<tr style="border-bottom: thin solid black;"><td>@virtual</td><td>サポートされないシノニム。代わりに @abstract を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@extends</td><td>サポートされないシノニム。代わりに @augments を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@constructor</td><td>サポートされないシノニム。代わりに @class を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@const</td><td>サポートされないシノニム。代わりに @constant を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@defaultvalue</td><td>サポートされないシノニム。代わりに @default を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@desc</td><td>サポートされないシノニム。代わりに @description を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@host</td><td>サポートされないシノニム。代わりに @external を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@fileoverview</td><td>サポートされないシノニム。代わりに @file を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@overview</td><td>サポートされないシノニム。代わりに @file を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@emits</td><td>サポートされないシノニム。代わりに @fires を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@func</td><td>サポートされないシノニム。代わりに @function を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@method</td><td>サポートされないシノニム。代わりに @function を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@var</td><td>サポートされないシノニム。代わりに @member を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@emits</td><td>サポートされないシノニム。代わりに @fires を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@arg</td><td>サポートされないシノニム。代わりに @param を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@argument</td><td>サポートされないシノニム。代わりに @param を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@prop</td><td>サポートされないシノニム。代わりに @property を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@returns</td><td>サポートされないシノニム。代わりに @return を使用。</td></tr>
+
<tr style="border-bottom: thin solid black;"><td>@exception</td><td>サポートされないシノニム。代わりに @throws を使用。</td></tr>
+
</table>
+
 
+
最新英語版: [https://make.wordpress.org/core/handbook/ Core Contributor Handbook]  > [https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/ JavaScript Documentation Standards]
+
 
+
[[Category:WordPress の開発]]
+

2020年1月3日 (金) 19:13時点における最新版

このページは https://ja.wordpress.org/team/handbook/coding-standards/inline-documentation-standards/javascript/ へ移動しました。