0

クロージャ メソッドで作成された JavaScript シングルトン オブジェクトがあります。

/**
 * This is the singleton.
 *
 * @namespace window.Something.Singleton
 */
window.Something.Singleton = (function() {
  /**
   * Foo method.
   *
   * @return {String} this method always returns with <code>bar</code>
   */
  function _foo() { return "bar"; }

  /**
   * @lends window.Something.Singleton#
   */
  return {
    /**
     * @borrows window.Something-_foo
     * @function
     */
    foo: _foo
  };
}());

しかし、jsdoc-toolkit_fooは、メソッドからメソッドへの継承されたドキュメントを生成しませんfoo。

@seeそれが機能する代わりに書いた場合@borrows（正しいメソッドへのリンクを挿入します）、メソッドのドキュメントをコピーして貼り付けて、公開ドキュメントも作成したくありませんfoo。

4

2 に答える 2

3

私はいくつかのテストを行いましたが、良いニュースと悪いニュースがあります:)。@borrows良いニュースは、Singleton doc コメントにタグを入れることでこれを機能させることができるように見えることです:

/**
 * This is the singleton.
 *
 * @namespace Something.Singleton
 * @borrows Something.Singleton-_foo as foo
 */
Something.Singleton = (function() {
   // etc
})());

しかし、これにはいくつかの影響があり、良い面と悪い面があります。

  • foo機能は とマークされていますstatic。私はあなたのコードを理解しているので、これはおそらく良いことです。
  • 現在表示されているコード (つまり、シングルトンのメソッドがないなど) を使用すると@lends、わかりやすくするためにタグを含めたくない場合を除き、タグを完全に省略することができます。すべてのメソッドが@borrows最上位のシングルトン名前空間にリストされている場合、返されたオブジェクトでそれらをさらに文書化する必要はありません。繰り返しますが、これはおそらく良いことです。
  • 悪いニュースは、借用したメソッドが明示的にマークされていない限り、これを機能させることができなかったことです@public。これにより、ドキュメントに重複して表示されます。これはやむを得ないと思います.jsdoc-toolkitがメソッドを非公開と判断した場合、ドキュメントが作成されないため、参照できません(私はWARNING: Can't borrow undocumented Something.Singleton-_foo.. メソッドが公開されている場合は、ドキュメントに表示されます。

したがって、これは機能します：

/**
 * This is the singleton.
 *
 * @namespace Something.Singleton
 * @borrows Something.Singleton-_foo as foo
 */
Something.Singleton = (function() {
  /**
   * @public
   * Foo method.
   *
   * @return {String} this method always returns with <code>bar</code>
   */
  function _foo() { return "bar"; }

  return {
    foo: _foo
  };
}());

_foo... のドキュメントをにコピーしますが、ドキュメント ページにもfoo表示されます。_foo

Method Summary
<inner>  _foo()
<static>  Something.Singleton.foo()

おそらく最善の回避策は、doc コメントのように@borrows完全かつ明示的に名前_fooを付けるのを忘れて、それをパブリック関数としてマークすることです (内部関数にアンダースコアを付けなかった場合は省くことができますが、これは jsdoc-toolkit に処理するように指示します)別段の指示がない限り、非公開として):Something.Singleton.foo@public

/**
 * This is the singleton.
 *
 * @namespace Something.Singleton
 */
Something.Singleton = (function() {
  /**
   * @name Something.Singleton#foo
   * @public
   * @function
   * Foo method.
   *
   * @return {String} this method always returns with <code>bar</code>
   */
  function _foo() { return "bar"; }

  return {
    foo: _foo
  };
}());

これにより、探しているコード ドキュメントが作成され、関連する実際のコードの横にコメントが表示されます。コンピューターにすべての作業を行わせるというニーズを完全に満たすことはできません-コメントで非常に明確にする必要があります-しかし、それはあなたが最初に持っていたものよりも、そうではないにしても、同じくらい明確だと思います.はるかにメンテナンスが必要だとは思いません (元の例でも、名前を変更した場合はすべてのドキュメント コメントを変更する必要がありますSomething.Singleton)。

于 2011-04-13T20:55:15.727 に答える
2

http://code.google.com/p/jsdoc-toolkit/wiki/TagBorrows

@borrows otherMemberName as thisMemberName
otherMemberName- 必須: 他のメンバーへのネームパス。
thisMemberName- 必須: このクラスでメンバーに割り当てられる新しい名前。

/** @constructor */
function Remote() {
}

/** Connect to a remote address. */
Remote.prototype.transfer = function(address, data) {
}

/**
 * @constructor
 * @borrows Remote#transfer as this.send
 */
function SpecialWriter() {
    this.send = Remote.prototype.transfer;
}

Remote#transfer のドキュメントは、SpecialWriter#send のドキュメントとしても表示されます。

于 2011-04-13T16:01:18.830 に答える