У меня есть следующая структура AMD для моих модулей.
/* globals define */
define([""], function() {
'use strict';
var module = {};
function _somePrivateFunc() {}
function somePublicFunc() {}
module.somePublicFunc = somePublicFunc;
return module;
});
Я борюсь с JSDoc, чтобы заставить его работать с моими модулями. До сих пор я мог заставить его работать как
/* globals define */
/**
* Module description here
* @module some/module/name
*/
define([""], function() {
'use strict';
/**
* @alias module:some/module/name
*/
var module = {};
function _somePrivateFunc() {}
function somePublicFunc() {}
/**
* Some property description here
* @itWorks
*/
module.somePublicFunc = somePublicFunc;
return module;
});
Как видите, это работает. Но я хочу, чтобы мои комментарии к документам определялись в объявлениях функций, а не там, где я добавляю их в модуль. Я хочу добиться этого:
/* globals define */
/**
* Module description here
* @module some/module/name
*/
define([""], function() {
'use strict';
/**
* @alias module:some/module/name
*/
var module;
/**
* Somehow make this appear in JSDoc
* @extend module:some/module/name
* @private
*/
function _somePrivateFunc() {}
/**
* Make this appear in JSDoc for sure.
*/
function somePublicFunc() {}
// I want this to NOT annotate, and I want the property to gather JSDoc
// from the func. declaration
module = {
somePublicFunc: somePublicFunc
};
return module;
});
Последнее - это то, чего я хотел бы достичь, но, к сожалению, это не работает :(
Есть идеи? Ваше здоровье
Редактировать:
Я добился некоторого прогресса. Имейте в виду, что если я напишу только это:
define('dep', function(require) {
/**
* @exports dep
*/
var module = {};
/**
* Adds two numbers together.
* @param {Number} a the first number
* @param {Number} b the second number
* @return {Number} the sum of a and b
*/
function sum(a, b) {
return a + b;
}
module.sum = sum;
return module;
});
тогда вывод пустой. JSDoc не может правильно генерировать документацию. Хотя если я добавлю аннотацию @method <name>
к своей функции, то она автоматически отлично работает. Интересно, но недостаточно добавить только аннотацию @method
без имени. Мое окончательное рабочее решение выглядит так:
define('dep', function(require) {
/**
* @exports dep
*/
var module = {};
/**
* Adds two numbers together.
* @func sum
* @param {Number} a the first number
* @param {Number} b the second number
* @return {Number} the sum of a and b
*/
function sum(a, b) {
return a + b;
}
/**
* Creates a closure. Adds two numbers together
* @func _add
* @param {Number} a the closure variable to add statically
* @return {Function} the closure
* @private
*/
function _add(a) {
return function(b) {
return a + b;
};
}
module.sum = sum;
return module;
});
Флаг CLI -p
позволяет отображать закрытые члены в документации.
Дополнительная информация
Я смог сделать внутренние ссылки только одним способом через мой пример кода:
/**
* Adds two numbers together.
* @func sum
* @param {Number} a the first number
* @param {Number} b the second number
* @return {Number} the sum of a and b
* @see {@link module:dep~_add|_add}
*/
function sum(a, b) {
return a + b;
}