Ответ 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. Если вы можете предоставить некоторый пример кода, я могу дать вам более полезный ответ.