Вложенные методы в боковой панели JSDoc

Благодаря ответу, найденному здесь:

Моя документация JavaScript хорошо организована и хорошо отформатирована. Каждое пространство имен является "родителем" методов, содержащихся внутри. Тем не менее, навигация не такая гранулированная, как хотелось бы.

После компиляции/рендеринга с помощью инструмента node.js с помощью простой команды (jsdoc file1.js file2.js) документы будут сгенерированы в шаблон по умолчанию. Этот шаблон по умолчанию отображает мои пространства имен в навигации на боковой панели, но не отображает методы, которые каждый содержит.

Вы можете подделать список методов, добавив директиву @class к каждому методу, но, как мы знаем, они не являются действительно классами.

Мне бы очень хотелось увидеть навигацию на боковой панели:

My Project

 - namespace 1
    - method.a
    - method.b
    - method.c

 -namespace 2
    - method.d
    - method.e

Любое направление документации, которую я упустил, будет с благодарностью.

[edit to add:]

При экспериментировании @class выполняет почти то, что я хочу, но за некоторыми исключениями:

В нем перечислены классы над пространствами имен. Мне это не нравится, поскольку пространства имен являются "родителями" как есть.
В этом смысле JavaScript не имеет классов. Не те, которые называются "классами" с этой номенклатурой. Это создает странное отключение при чтении документа, чтобы увидеть список "классов".
Автоматически добавляет "новый" оператор. Не все методы имеют конструкторы... вы можете увидеть проблему!

[править: пример кода]

Итак, вот текущая структура. Прежде чем комментировать его с помощью комментариев JSDoc, вот базовый подход:

var app =  app || {};
app.utils = {
    whizbang: function() {},
    geegolly: function() {}
  };
app.render = {
    thestuff: function(params) {},
    thethings: function(params) {}
  }
}

Таким образом, используя нотацию объектного литерала, верхний уровень является "пространством имен" для всего приложения, но внутри него есть пространства имен под разными именами. Здесь у меня есть суб-пространство имен, специфичное для утилит, а другое - для рендеринга. Каждый из них может иметь свойства, но, что более важно, каждый из них содержит функции. Именно эти функции должны появляться на боковой панели. Теперь, чтобы скомпоновать его с моей текущей моделью для JSDoc:

/** 
 * @file MyApp.js This is an awesome description of MyApp.js
 * 
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

/**
 * Description of my main namespace!
 * 
 * @namespace app
 */
var app = app || {};

/**
 * This is a description of my sweet utilities namespace!
 *                                                                              
 * @memberof app
 * @type {object}
 * @namespace app.utils
 */
app.utils = {
  /**
   * app.utils.whizbang is an awesome function with magical powers. I sure wish
   * it would appear in the sidebar as a member of app.utils!
   * 
   * @memberof app.utils
   * @method whizbang
   * 
   * @param {method} [successCallback] Method invoked on successful attempt.
   * @param {method} [errorCallback] Method invoked on unsuccessful attempt.
   * 
   */
   whizbang: function(successCallback, errorCallback) { // do utility stuff! }
}

/**
 * This is a description of the best rendering namespace ever.
 *                                                                              
 * @memberof app
 * @type {object}
 * @namespace app.render
 */
app.render = {
  /**
   * app.render.thethings renders the things! I wish it would render to the sidebar...
   * 
   * @memberof app.render
   * @method thethings
   * 
   * @param {method} node The node to which thethings are rendered
   * 
   */
   thethings: function(node) { // do rendering stuff! }
}

Ответ 1

Пробовали ли вы использовать тег @lends? Здесь будет полезен пример ваших комментариев кода и документа.

Так как я не знаю, как выглядит ваш код, я просто приведу пример того, как я использую JSDoc с нашей внутренней структурой, у которой много идиосинкразий (эй, я не писал это, я просто нужно использовать его).

Чтобы дать некоторый контекст, у нас есть объект context, который может создавать приложения и модули (приложения - это всего лишь модули с методом start):

/** @namespace MyApp */
var MyApp = context.app('myApp').use('module1', 'module2', 'underscore');

У нас есть система впрыска зависимостей для магистрали, которая использует шаблон angular -style для выражения зависимостей:

/** 
* The constructor for MyModel
* @memberof MyApp
* @param {object?} attrs
* @param {object?} options
* @param {AppUtils} appUtils
* @constructor
*/  
MyApp.MyModel = function(attrs, options, appUtils) {
    this.options = options;
    this.utils = appUtils;
}

// This is injected by the dependency resolver at instantiation time
// No additional JSDoc comments are necessary, it actually gets this right
MyApp.MyModel.prototype = {

    idAttribute: 'customId',

    defaults: {
        customId: '',
        name: '',
        birthday: null
    }

};

// Registers MyModel with the IOC container as 'myModelName'
MyApp.model('myModelName', [
    'attrs',
    'options',
    'appUtils'
    MyApp.MyModel
]);

И тогда в другом файле может быть введен экземпляр myModelName, добавив его в этот массив зависимостей внизу.

Забавно, что JSDoc на самом деле очень хорошо разбирается в этой конкретной договоренности, пока я не пытаюсь получить слишком фантазию... но следующий шаблон, по-видимому, слишком запутан для него:

/**
 * @memberof MyApp
 * @param {MyApp.MyModel} myModel
 * @param {urlParser} urlParser
 * @constructor
 */
MyApp.SomeService = function(myModel, urlParser) {

    return {

        foo: function() {
            //whatever
        },

        bar: function() {
            //whatever
        }

    };

};

MyApp.service('someModuleName', [
    'myModelName',
    'urlParser',
    MyApp.SomeService
]);

Единственное, что я нашел, которое дает мне что-то близкое к желаемому результату, - это использовать тег @lends, чтобы сообщить JSDoc, что конкретный объект/свойство/метод "завален" как другое свойство. Например, чтобы документировать свойство attributes базовой модели (которая якобы определяется свойством defaults), мы делаем следующее:

MyApp.MyModel.prototype = {

    idAttribute: 'customId',

    /** @lends MyApp.MyModel.prototype.attributes */
    defaults: {
        customId: '',
        name: '',
        birthday: null
    }

};

И в том случае, когда служба возвращает объект, единственный способ, которым мы обнаружили, чтобы эти свойства объектов были задокументированы, выглядит следующим образом:

/**
 * @memberof MyApp
 * @param {MyApp.MyModel} myModel
 * @param {urlParser} urlParser
 * @constructor
 */
MyApp.SomeService = function(myModel, urlParser) {

    /** @lends  MyApp.SomeService.prototype */
    return {

        foo: function() {
            //whatever
        },

        bar: function() {
            //whatever
        }
    };

};

Я понятия не имею, было ли это полезно, но, возможно, это даст вам некоторые идеи для вещей, которые вы можете попробовать с помощью @lends. Если вы можете предоставить некоторый пример кода, я могу дать вам более полезный ответ.