Skip to content

Latest commit

 

History

History
169 lines (137 loc) · 4.96 KB

gudelines-typedoc-comment.md

File metadata and controls

169 lines (137 loc) · 4.96 KB
Raw

Typedoc comment guidelines

Typedoc で映えるコメントの書き方のためのガイドラインページ

はじめに

  • JsDoc でたくさん書く必要があるのは型情報が無いから。 JS ではこれがとても重要な情報であるため。
    • TypeDoc は何も書かなくても型情報は自動生成してくれる。本当に必要なコメントに集中しよう。

ガイドライン

公開クラス、公開メソッドには説明を記載する

非公開メソッド、内部変数は Typedoc コメントは基本不要。

シンプルに書く

× 不要なアノテーション

/**
 * @class Dialog
 * @brief 汎用ダイアログクラス
 *        jQM の popup widget によって実装
 */
  • @class は Typedoc が既定で記載するため被る
  • @brief は doxygen であるが、説明を書くのがメインなので不要

Typedoc が対応しているアノテーションは以下。そのほかは飾りつけはしてくれる。

annotation description
@param 関数の引数
@returns 関数の戻り値 (推奨)
@return 関数の戻り値

× 不要な型情報

/**
 * URL遷移
 *
 * @param {String}          url          [in] 遷移 URL を指定 (相対パス/絶対パス/フラグメント)
 * @param {String}          [transition] [in] transition に使用する effect を指定 (任意)
 * @param {Boolean}         [reverse]    [in] transition に使用する direction を指定 true:reverse/false:通常 (任意)
 * @param {NavigateOptions} [options]    [in] Backbone.Router.navigate() に渡されるオプション (任意)
 */
static navigate(url: string, transition?: string, reverse?: boolean, options?: NavigateOptions): void;
  :
}}
  • {型} は不要. {string} なのか {String} なのかで悩まなくて良い
  • [options] のようなオプショナル引数も不要
  • [in] 入力/出力引数の区別は基本不要. (本来は C++ のメモリ確保の責任を明示したもの. JavaScript で出力引数を使うなら、まずはオブジェクト返しにできないか考慮する)

英語・日本語両対応したコメントの書き方

◎クラス/インターフェイスコメント
/**
 * @es Cancelable Promise object interface definition
 * @ja キャンセル可能な Promise オブジェクトのインターフェイス定義
 */

◎メソッドコメント
/**
 * @en call abort() to under the management Promises.
 * @ja 管理対象の Promise に対して abort を発行
 *
 * @param info
 *  - `en` abort() argument
 *  - `ja` abort() に渡される引数
 * @returns
 *  - `en` The cancellation to cancel processing is prohibited.
 *  - `ja` キャンセル処理に対するキャンセルは不可
 */
public cancel(info?: object): IPromiseBase<any> {
  :
}
  • 主コメントには @en, @ja アノテーションを使用する
  • 引数, 戻り値には en, ja code記法 とリスト記法を組み合わせる

応用

アノテーション

@internal

/**
 * @en Utility class for appling the patch to the run time environment.
 * @ja 実行環境用 Patch 適用ユーティリティクラス
 *
 * @internal
 */
 export class Patch {
        /**
         * @en Apply the patch
         * @ja パッチの適用
         *
         * @internal
         */
        public static apply(): void {
            :
        }
 }
  • export された class や public メンバだが、内部でのみ使用したい表明に使用する

@example

/**
 * @es Judge the error is canceled.
 * @ja エラー情報がキャンセルされたものか判定
 *
 * @example <br>
 *
 * ```ts
 *  :
 *  .catch((reason: ErrorInfo) => {
 *      if (!isCanceledError(reason)) {
 *          handleErrorInfo(reason);
 *      }
 *   });
 *  :
 * ```
 *
 * @param error
 * @returns
 *  - `en` true: canceled error / false: others
 *  - `ja` true: キャンセル / false: その他エラー
 */
function isCanceledError(error: Error | string): boolean;

マークダウン記法

Typedoc では、コメントに HTML タグおよびマークダウン記法が基本的に使用可能。
特に内部オブジェクトへのリンクは便利で可読性を損なわないため積極的に使用しよう。

/**
 * @en Generate canceled error information. <br>
 *     The [[ErrorInfo]] object generated by this function has [[RESULT_CODE.CANCELED]] code.
 * @ja キャンセルエラー情報生成 <br>
 *     この関数で生成された [[ErrorInfo]] は [[RESULT_CODE.CANCELED]] を格納する
 *
 * @param tag
 *  - `en` Log tag information
 *  - `ja` 識別情報
 * @param cause
 *  - `en` low-level Error object
 *  - `ja` 下位のエラーを指定
 * @returns
 */
export function makeCanceledErrorInfo(tag?: string, cause?: Error): ErrorInfo {