Лучший способ зарегистрировать анонимные объекты и функции с [закрытым] jsdoc
Править: Это - технически 2 вопроса о части. Я выбрал лучший ответ, который касается вопроса в целом и связанный с ответом, который обрабатывает конкретный вопрос.
Что лучший способ состоит в том, чтобы зарегистрировать анонимные объекты и функции с jsdoc?
/**
* @class {Page} Page Class specification
*/
var Page = function() {
/**
* Get a page from the server
* @param {PageRequest} pageRequest Info on the page you want to request
* @param {function} callback Function executed when page is retrieved
*/
this.getPage = function(pageRequest, callback) {
};
};
Ни один PageRequest возразите или callback существуйте в коде. Им предоставят getPage() во времени выполнения. Но я хотел бы смочь определить, каковы объект и функция.
Мне может сойти с рук создание PageRequest возразите для документирования этого:
/**
* @namespace {PageRequest} Object specification
* @property {String} pageId ID of the page you want.
* @property {String} pageName Name of the page you want.
*/
var PageRequest = {
pageId : null,
pageName : null
};
И это прекрасно (хотя я открыт для лучших способов сделать это).
Что лучший способ состоит в том, чтобы зарегистрировать callback функция? Я хочу заставить его знать в документе, что, например, функция обратного вызова в форме:
callback: function({PageResponse} pageResponse, {PageRequestStatus} pageRequestStatus)
Какие-либо идеи, как сделать это?
3 ответа
Вы можете документировать то, что не существует в коде, используя тег @name:
/** Description of the function
@name IDontReallyExist
@function
@param {String} someParameter Description
*/
/** The CallAgain method calls the provided function twice
@param {IDontReallyExist} func The function to call twice
*/
exports.CallAgain = function(func) { func(); func(); }
Вот документация по тегу @name . Вы также можете найти пути имен полезными.
Вы можете использовать @see для ссылки на другой метод в том же классе. Этот метод никогда не будет использоваться, он будет использоваться только для целей документации.
/**
* @class {Page} Page Class specification
*/
var Page = function() {
/**
* Get a page from the server
* @param {PageRequest} pageRequest Info on the page you want to request
* @param {function} callback Function executed when page is retrieved
* @see #getPageCallback
*/
this.getPage = function (pageRequest, callback) {
};
/**
* Called when page request completes
* @param {PageResponse} pageResponse The requested page
* @param {PageRequestStatus} pageRequestStatus Status of the page
*/
//#ifdef 0
this.getPageCallback = function (pageResponse, pageRequestStatus) { };
//#endif
};
Если вы используете какую-то систему сборки, фиктивный метод можно легко исключить из сборки.
@link может добавлять встроенные ссылки на методы и классы.
/**
* Get a page from the server
* @param {PageRequest} pageRequest Info on the page you want to request
* @param {function} callback Function executed when page is retrieved<br />
* function({@link PageResponse} pageResponse,{@link PageRequestStatus} pageRequestStatus)
*/
this.getPage = function (pageRequest, callback) {
};
Не идеально, но выполняет свою работу.