Как включить уже документированный метод в jsdoc-toolkit?

Question

У меня есть одноэлементный объект 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 способ иметь публичную документацию.

Answer 1

Я провел несколько тестов, и у меня есть хорошие и плохие новости :). Хорошей новостью является то, что, похоже, вы можете заставить это работать, добавив тег @borrows в комментарии к документу Singleton:

/**
 * 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()

Вероятно, лучший обходной путь - просто забыть @borrows полностью и явно назвать _foo как Something.Singleton.foo в комментарии к документу, пометив его как публичную функцию (вы можете обойтись без @public, если вы не назвали ваша внутренняя функция с подчеркиванием, но это говорит jsdoc-toolkit рассматривать ее как приватную, если не указано иное):

/**
 * 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).

Answer 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;
}

Любая документация для удаленной передачи # также будет отображаться как документация для отправки SpecialWriter #.