JavaScript API ドキュメンテーション・コメントスタンダード 日本語訳

本日は Drupal コミュニティで提案されているスタンダードの中で JavaScript API のドキュメントに関するスタンダードを翻訳してご紹介できればと思います。

今回のものはこれまで続けてきた Drupal コーディングスタンダード日本語訳の中でも少しマニアックな部類に入るでしょうか。コードそのものではなくコードの合間に書くドキュメンテーション/コメントのためのスタンダードとなっています。もとのドキュメント自体がまだ発展途上・作成途中ということもあり、内容は比較的コンパクトです。

以下がその翻訳文となります。最終更新日が 2014 年 01 月 28 日のバージョンをもとにしています。日本語としてのわかりやすさを意識し、ところによって原文直訳、ところによって大幅な意訳にしてします。原文の厳密なニュアンスが知りたい方はぜひ原文の方にあたってみてください。

JavaScript API ドキュメンテーション・コメントスタンダード 日本語訳

このコンテンツはいまだ作成中です。全体の議論については #1337022: [policy,do no patch] JS ドキュメンテーションパーサと互換性のある javaScript ドキュメントスタンダードの作成/適用 を、 drupal.js についてはこちらのサンプルドキュメンテーションを、 Backbone オブジェクトについてはこちらのサンプルドキュメンテーションをご覧ください。

JavaScript コードはドキュメンテーションヘッダとあわせて書くようにしましょう。ドキュメンテーションヘッダは http://drupal.org/node/1354 で説明されている PHP ドキュメンテーションヘッダとよく似たものにするべきです。コードとドキュメントをパースする最初のステップとして、 JSDoc3 パーサを使用するための変更点があります。全般的に PHP スタンダードにできるかぎり従った上で、次の変更点を押さえておきましょう：

• JavaScript のアイテム（メソッド、オブジェクトコンストラクタ、プロパティ、関数、変数など）にはすべてドキュメンテーションヘッダをつける必要があります。そうでないとパーサはまったく認識てくれません（ API モジュールとは異なります。 API モジュールではドキュメンテーションヘッダがあるかどうかにかかわらずすべての PHP アイテムをピックアップします）。
• PHP に使う @tags すべてがサポートされるわけではありません。 http://drupal.org/node/1354 で取り上げられているタグのうち、 @file 、 @param 、 @return 、 @see 、 @link/@endlink 、 @code/@encode 、@throws のみ使いましょう。
• @param や @return タグにおいてデータの型を表すには {} かっこの中にデータタイプを入れましょう。 @param {タイプ名} パラメータ名 、 @return {タイプ名} といった形にします。オブジェクト以外のデータについては、 number 、 string 、 bool 、 null 、 undefined 、 object 、 array 、 function を使いましょう。特定のクラスのオブジェクトについては、クラス名（コンストラクタ名）を使いましょう。これは組み込みの JavaScript クラス（ Date 、 RegExp ）や DOM エレメント（ Document 、 Checkbox ）、 Drupal 固有のクラス（ Drupal.AJAX ）などになるでしょう。
• 追加のタグ： PHP や JavaScript の関数が投げる例外について説明する @throws のように、 JavaScript 関数によってトリガされるイベントの説明を @fires を使って書きましょう。加えて、そのイベントがカスタムイベント（キー押下などの標準のイベントとは異なるイベント）の場合、イベントをトリガする関数内の最初の行の直前にドキュメンテーションブロックを追加しましょう。その際は @event タグを使ってそのイベントそのものについて説明します（詳細は下記サンプルをご覧ください）。各カスタムイベントにはそれぞれひとつの @event ブロックを書いて、カスタムイベントをトリガする各関数には @fires を使いましょう。
• 追加のタグ：名前空間やクラスとして使われていないオブジェクトについて説明する際は、 @property {型} 名前 タグを使ってそのプロパティについての説明を書きましょう（これらは関数における @param のような働きをします）。
• どのようなタイプのアイテムに関する説明なのか JSDoc が理解するのを助けるために、多くの場合追加の記法が必要となります。次のように、ドキュメンテーションブロックの末尾にタグを追加しましょう：
  • 説明されているものの名前がコードの中のものと異なれば（これはたいてい Bar.foo のようにクラス名を含むものではなく foo のようなプロパティ名になる場合にあたります）、説明されているものの名前を JSDoc に伝えるためドキュメンテーションブロックの最下部あたりで @name (名前) を使いましょう。
  • 関数がクラスコンストラクタであることを示すために @constructor を使いましょう。 @constructor 行の直後（でドキュメンテーションブロックの最下部のところ）に、 @classdesc で始まる行を追加してコンストラクタによって作られるクラスの目的について説明を書きましょう。
  • ほとんどの場合 @function を使う必要はありません。 JSDoc は、上記のタグのいずれかによってオーバーライドされていない場合、関数として宣言されたものはすべて通常の関数かメソッドであるものと仮定します。

サンプルはこちらです：

// drupal.js ファイルより:
/**
 * JavaScript の settings やその他 Drupal のための情報を保持する。
 *
 * @namespace
 */
var Drupal = Drupal || {
   // ...
  /**
   * Drupal の behaviors を保持する。
   *
   * @namespace
   * @name Drupal.behaviors
   */
  'behaviors': {},
  // ...
}
// tabledrag.js のようなファイル内:
/**
 * @file ドラッグ可能なテーブルのための JavaScript。
 */
(function ($) {
/**
 * テーブルにドラッグのふるまいを付加する。
 *
 * @property {function} attach
 *   このアタッチ関数特有の説明はここに書く。
 */
Drupal.behaviors.tableDrag = {
  attach: function (context, settings) {
    // ...
  }
};
/**
 * カレントウィジェットの foo の値を返す。
 *
 * Drupal 名前空間の中の通常の関数の説明はここに書く。
 *
 * @return
 *   カレントウィジェットの foo の値。
 */
Drupal.getCurrentFoo = function () {
  // ...
};
/**
 * テーブルドラッグオブジェクトを生成する。
 *
 * @param {HTMLTableElement} table
 *   ドラッガブルなテーブルのための DOM オブジェクト。
 * @param {object} tableSettings
 *   テーブルのための設定。
 *
 * @constructor
 * @classdesc テーブルとそのフィールドを操作するためのドラッグ機能を提供する。
 */
Drupal.tableDrag = function (table, tableSettings) {
  // ...
}
/**
 * ウェイトと親となるフォーム要素を含んだ列を非表示にする。
 *
 * @fires columnschange
 * @see Drupal.tableDrag.showColumns
 */
Drupal.tableDrag.prototype.hideColumns = function() {
  // ...
  /**
   * Indicates that columns have changed in a table.
   * テーブル内の列が変化することを示す。
   *
   * @param type
   *   変更のタイプ： 'show' か 'hide' 。
   *
   * @event columnschange
   */
  $('table.tableDrag-processed').trigger('columnschange', 'hide');
  // ...
};
/**
 * ウェイトと親となるフォーム要素を含んだ列を表示する。
 *
 * @fires columnschange
 * @see Drupal.tableDrag.hideColumns
 */
Drupal.tableDrag.prototype.showColumns = function() {
  // このイベントは Drupal.tableDrag.hideColumns で説明されています
  $('table.tabledrag-processed').trigger('columnschange', 'hide');
};
}(jQuery));

・・・以上です。

いかがだったでしょうか？

Drupal 開発者にとって、 JS のドキュメントをここまで念入りに書く機会というのは比較的少ないのかなとは思いますが、実際にこういう機会がめぐってきたときにはサクサク書けるようベースの部分だけでも押さえておきたいところです。