Как правильно документировать тип параметра jQuery с помощью JSDoc?

Я пытаюсь задокументировать свою программу с синтаксисом JSDoc для себя и людей, которым придется смотреть на мой код. Я также пытаюсь улучшить свои навыки.

Для параметра типа jQuery я немного озадачен. Я знаю, что это объект, но он довольно распространен в моей программе, поэтому я думаю, что должен сначала объявить typedef для типа jQuery, а затем использовать его в качестве типа параметра. Поэтому я спрашиваю, будет ли это правильным способом сделать это?

/**
 * DOM object referenced by jQuery
 * @typedef {jQuery} $jQueryDomObject
 */

/**
* SOAP call that does ...
*
* @param {string} code Some desc ...
* @param {callback} fnctVa Some desc ...
* @param {$jQueryDomObject} $attrib Input field that ...
*/
myfunction = function (code, fnctVa, $attrib) {};

Я также нашел на SO этот вопрос, несколько похожий:
Как заставить JSDoc пометить мой параметр как объект jQuery?


javascript jquery jsdoc
person Jean-Philippe Martin    schedule 27.11.2013    source источник
comment
Правильно не делать вызов SOAP с использованием объекта jQ и разделять проблемы. Просто говорю. Тем не менее интересный вопрос.   -  person Benjamin Gruenbaum    schedule 28.11.2013
comment
Хорошо, я посмотрю на это. Не могли бы вы предложить образец вместо этого?   -  person Jean-Philippe Martin    schedule 28.11.2013
comment
Разделение интересов является принципом, а не шаблоном. Идея в этом случае (это применимо не только к графическому интерфейсу) состоит в том, что ваша логика представления и бизнес-логика не должны смешиваться таким образом. Некоторые распространенные шаблоны проектирования, которые решают эту проблему, — это посредник, наблюдатель и генератор событий. Некоторые архитектурные шаблоны, решающие эту проблему, — MVC, MVVM и MVP.   -  person Benjamin Gruenbaum    schedule 28.11.2013
comment
Спасибо за совет по архитектуре... хорошо, так что графический интерфейс не взаимодействует с данными напрямую и наоборот. Понятно.   -  person Jean-Philippe Martin    schedule 28.11.2013
comment
@ Jean-PhilippeMartin, я сделал почти то же самое, документируя устаревший код, к написанию которого я не приложил руку.   -  person Andy    schedule 28.11.2013

Ответы (2)


arrow_upward
22
arrow_downward

Для параметра, который является объектом jQuery, я часто просто делаю:

@param {jQuery} foo

И не надо дальше определять, что такое jQuery. Достаточно хорошо известно. Однако, если вы хотите, вы можете сделать это с помощью jsdoc 3:

/**
 * jQuery object
 * @external jQuery
 * @see {@link http://api.jquery.com/jQuery/}
 */

/**
 * SOAP call that does ...
 *
 * @param {string} code Some desc ...
 * @param {callback} fnctVa Some desc ...
 * @param {external:jQuery} $attrib Input field that ...
 */
var myfunction = function (code, fnctVa, $attrib) {};
person Louis    schedule 27.11.2013

arrow_upward
4
arrow_downward

Я также видел на github/js3doc:

@param {jQuery object} obj The jQuery object you're looking for.

или github/js3doc

@param {module:jquery} jquery Some desc...
person Jean-Philippe Martin    schedule 28.11.2013