14

I'm writing my own library for the project at work for a browser application and I am having the same old problem deciding how to comment the code.

I'm trying to follow the JsDoc syntax, but will probably continue the Google Closure Compiler way. I may end up using two @return and @returns tags in the documentation, just for portability sake (when I setup the auto-generation of the documentation).

Now, the question, how do you document the return of a custom anonymous object from a function? For example:

return {
    username: 'username',
    password: 'password',
    enabled:  true
};

JsDoc has an example of how a @param can be documented to expect object with certain fields, but not the @returns tag. Similarly, the Google Closure Compiler documentation of a Record Type is vague and has no example to work it out.

4

3 に答える 3

15

Closure-compiler は、JSDoc アノテーションのサブセットを使用します (独自のアノテーションをいくつか追加します)。完全なセットについては、コンパイラの注釈リファレンスを参照してください。/**JSDoc アノテーションは JavaDoc アノテーションに似ており、 (2 つの星)で始まるコメント ブロックです。多くの場合、コメントの各行は独自の で始まりますが、これ*は必須ではない規則です。1 行に 1 つの JSDoc タグのみが許可されますが、タグの引数は複数の行にまたがることができます。

注釈は通常、次のステートメントに適用されます。ここではいくつかの例を示します。

変数

/** @type {string} */ var a;

タイプキャスト

var b = /** @type {string} */ (window['foo']);

余分な括弧に注意してください

名前付き関数

/**
 * @param {string} bar
 * @return {boolean}
 */
function foo(bar) { return true; }

関数式

/** @type {function(string):boolean} */
var foo = function(bar) { return true; }

var foo2 =
  /**
   * @param {string} bar
   * @return {boolean}
   */
  function(bar) { return true; }

Typedef

複雑な型 (共用体やレコード型を含む) は、typedef を使用して利便性と保守性のために別名を付けることができます。これらの注釈は長くなる可能性がありますが、読みやすくするために複数行に分割できます。

/** @typedef {{
 *             foo:string,
 *             bar:number,
 *             foobar:number|string
 *           }}
 */
var mytype;

元の例では、そのような関数の戻り値に注釈を付ける方法がいくつかあります。最も具体的で便利なものの 1 つは、レコード タイプです。

/** @return {{username:string, password:string, enabled:boolean}} */
function() {
  return {
    username: 'username',
    password: 'password',
    enabled:  true
  }
}

余分に注意してください{}。また、レコード タイプはプロパティの名前変更を妨げないことにも注意してください。

usernameこの注釈は、関数が、passwordおよびenabledプロパティを持つ匿名型を返すことをコンパイラに伝えます。他の有効なオプションは、別の場所でインターフェイスを定義し、戻り値をそのインターフェイスに型キャストすることです。最も具体的でない注釈はObjector*です。

さまざまな可能な注釈を確認するには、コンパイラ プロジェクトの extern ファイルを参照してください。

于 2012-06-20T12:02:29.020 に答える
1

これを関数の上に置くと

function myFunction() {
    /**
     * Description of my function
     * @return {!Object.<string, string|boolean>} Returns an object containing username, password and enabled information
     */

    // Do stuff
    return {
        username: 'username',
        password: 'password',
        enabled:  true
    }
}
于 2012-06-20T10:21:08.233 に答える