На Global
Чтобы JSDoc Шаблон для создания документации, вы должны добавить атрибут @function с именем функции. Ваши две функции появятся в глобальной части шаблона.
jsdoc your-exemple.js
Но, из-за вашу функцию находятся в области видимости в анонимной функции (но не модуля для момента), вы делаете добавить функцию @private, чтобы сообщить, что функции не является действительно глобальным, но только доступным в его объеме. Но, поскольку по умолчанию JSDoc Generator Template игнорирует функции privateates, добавьте опции --private.
jsdoc your-exemple.js --private
Так что ваш код выглядит так.
(function() {
"use strict";
// ...
/**
* Reduces a sequence of names to initials.
* @function makeInits
* @private
* @param {String} name Space Delimited sequence of names.
* @param {String} sep A period separating the initials.
* @param {String} trail A period ending the initials.
* @param {String} hyph A hypen separating double names.
* @return {String} Properly formatted initials.
*/
function makeInits(name, sep, trail, hyph) {
function splitBySpace(nm) {
return nm.trim().split(/\s+/).map(function (x) { return x[0]; }).join(sep).toUpperCase();
}
return name.split(hyph).map(splitBySpace).join(hyph) + trail;
}
/**
* Reduces a sequence of names to initials.
* @function makeInitials
* @private
* @param {String} name Space delimited sequence of names.
* @return {String} Properly formatted initials.
*/
function makeInitials(name) {
return makeInits(name, '.', '.', '-');
}
// ...
}());
в класс
Если вы подвергаете содержание анонимного закрытия к переменной var Helper, это возможно класса. Таким образом, ваш код не будет частью глобального контента, а частью класса с @class, следующим за именем класса. И поскольку вы предоставите свою функцию в отношении модуля класса, вам не нужно объявлять функцию как конфиденциальную.
Но вы объясните, что ваша предыдущая функция является частью класса, поэтому вы должны использовать @memberOf с полным путем к свойству.
- Окончание по
., если это статический член (открыт через возврат).
- Окончание по
#, если это метод, не поддающийся воздействию (подвергается через него).
- Окончание по
~ если это частная функция, которая не отображается вообще (и @private).
Так
/**
* Helper Class
* @Class Helper
*/
var Helper = (function() {
"use strict";
// ...
/**
* Split by Space
* @function privateExemple
* @private
* @memberOf Helper~
* @return {String} ...
*/
function privateExemple() {
return "";
}
/**
* Reduces a sequence of names to initials.
* @function makeInits
* @memberOf Helper.
* @param {String} name Space Delimited sequence of names.
* @param {String} sep A period separating the initials.
* @param {String} trail A period ending the initials.
* @param {String} hyph A hypen separating double names.
* @return {String} Properly formatted initials.
*/
function makeInits(name, sep, trail, hyph) {
function splitBySpace(nm, sep) {
return nm.trim().split(/\s+/).map(function (x) { return x[0]; }).join(sep).toUpperCase();
}
return name.split(hyph).map(splitBySpace).join(hyph) + trail;
}
/**
* Reduces a sequence of names to initials.
* @method makeInitials
* @memberOf Helper#
* @param {String} name Space delimited sequence of names.
* @return {String} Properly formatted initials.
*/
this.makeInitials = function makeInitials(name) {
return makeInits(name, '.', '.', '-');
}
// ...
return {
makeInits: makeInits
};
}());
В Molule
Но в вашем случае вы используете exports так, что означает, что ваш файл является модулем. Поэтому вы должны описать это с помощью @module и имени. Итак, все, что вы ранее комментировали, будет не частью Global, а теперь частью вашего модуля. И поскольку вы предоставите свою функцию за модулем Helper, вам не нужно объявлять функцию как конфиденциальную.
/**
* Helper Module
* @module Helper
*/
exports.helper = (function() {
"use strict";
// ...
/**
* Reduces a sequence of names to initials.
* @function makeInits
* @memberOf module:helper.
* @param {String} name Space Delimited sequence of names.
* @param {String} sep A period separating the initials.
* @param {String} trail A period ending the initials.
* @param {String} hyph A hypen separating double names.
* @return {String} Properly formatted initials.
*/
function makeInits(name, sep, trail, hyph) {
function splitBySpace(nm) {
return nm.trim().split(/\s+/).map(function (x) { return x[0]; }).join(sep).toUpperCase();
}
return name.split(hyph).map(splitBySpace).join(hyph) + trail;
}
/**
* Reduces a sequence of names to initials.
* @function makeInitials
* @private
* @memberOf module:helper~
* @param {String} name Space delimited sequence of names.
* @return {String} Properly formatted initials.
*/
function makeInitials(name) {
return makeInits(name, '.', '.', '-');
}
// ...
return {
makeInitials: makeInitials
};
}());
модуля и класса
Но, потому что вы подвергаете через var Helper как класс и через exports в качестве модуля можно документировать и в пути.
/**
* Helper Class
* @class Helper
* @memberOf module:helper~
* @see {@link module:helper|Module}
*/
var Helper = (function() {
"use strict";
// ...
/**
* Reduces a sequence of names to initials.
* @function makeInits
* @memberOf module:helper.
* @param {String} name Space Delimited sequence of names.
* @param {String} sep A period separating the initials.
* @param {String} trail A period ending the initials.
* @param {String} hyph A hypen separating double names.
* @return {String} Properly formatted initials.
*/
function makeInits(name, sep, trail, hyph) {
function splitBySpace(nm) {
return nm.trim().split(/\s+/).map(function (x) { return x[0]; }).join(sep).toUpperCase();
}
return name.split(hyph).map(splitBySpace).join(hyph) + trail;
}
/**
* Reduces a sequence of names to initials.
* @function makeInitials
* @private
* @memberOf module:helper~
* @param {String} name Space delimited sequence of names.
* @return {String} Properly formatted initials.
*/
function makeInitials(name) {
return makeInits(name, '.', '.', '-');
}
// ...
return {
makeInitials: makeInitials
};
}());
/**
* helper Module
* @module helper
*/
exports.helper = Helper;
Пространство имен или класс?
Разница между классом и пространством имен - это просто класс, выставляющий некоторые объекты/функции через this и не подлежит действию. Если к этому ничего не добавлено, у вас есть пространство имен, поэтому просто замените @class на @namespace, и этот код будет помещен в соответствующее пространство пространства имен.
Вы также проверяете, не является ли ваш класс не Mixin (просто используется поверх класса, но никогда напрямую), или интерфейс (определенный, но не реализуемый), если он является дополнительным классом другого класса.
и т.д.
Смотрите документ: http://usejsdoc.org/index.html
Я попробовал это. «Сайт» генерируется беззвучно. Страница пуста под заголовком. В моем источнике JavaScript есть две функции, экспериментально прокомментированные. Эти функции находятся внутри «модулей», то есть локальных в анонимных функциях, представляющих тело модуля. –
Возможно, потому, что вы не используете свойство '@ memberOf' для ссылки на эту функцию в модуле, поэтому модуль' @ memberof': MyModuleName ~ может выполнить эту работу. Отредактируйте сообщение, чтобы предоставить код, который не отображается должным образом в вашей документации, если вы хотите. –
Что-то вроде этого, надеюсь. Я попробовал модуль @memberOf: helper ~ ', безрезультатно. На самом деле мой модуль анонимен, поэтому я не удивлен. –