为了避免在我的JavaScript代码使用new
,我写的工厂来创建对象。
我已经尝试了许多组合,让我最满意的结果之一是:
/**
* Document module
* @module app/document
*/
(function () {
'use strict';
/**
* Factory that creates a document object.
* @alias module:app/document.factory
* @return {document}
*/
function document() {
/**
* Get document id
* @method id
* @return {String}
*/
var id = function id() {...},
api = {
id: id
};
return api;
}
/**
* This module exports the {@link module:app/document.factory|factory} function.
*/
module.exports = document;
}());
这些注释的问题是没有定义document
对象。因此,我不能引用该对象在另一个对象,并且当我扩展了这个目的我不能继承其文档。
什么是记录这种对象的适当方法?
如果我使用@typedef
标签,我得到的静态factory
方法,妥善记录的document
对象,但没有被JSDoc产生id
方法文档:
/**
* Document module.
* @module app/document
*/
(function () {
'use strict';
/**
* Factory that creates a document object.
* @function module:app/document.factory
* @return {document}
*/
function factory(agent) {
/**
* @callback document~id
* @returns {String}
*/
var id = function id() {...},
/**
* @typedef document
* @property {document~id} id
*/
document = {
id: id
};
return document;
}
module.exports = factory;
}());
我给你的建议是使用@typedef定义类型,然后用@type注释module.exports =工厂以及定义模块的出口{} FactoryDefinition
/** @typedef {{ id: !string }} */
var DocumentDefinition;
/** @typedef {!function(!object):!DocumentDefinition} */
var FactoryDefinition;
/** @type {FactoryDefinition} */
module.exports = factory
我总是用我的模块封装外的@typedef
,我总结了一套完整的由模块暴露功能。这是我设法得到的代码完成我的WebStorm IDE,并生成有用的HTML文档的唯一途径。
/** @namespace SharedLib */
/**
* @typedef SharedLib.PriorityQueueFactory
* @function
* @template T
* @param {function(T, T): Boolean} comparator Comparison function like for <code>Array.prototype.sort</code>
* @return {{pop: function(Array<T>): Array<Array<T>| T>, push: function(Array<T>, T): Array<T>}} an object containing the functions to manage the queue
*/
(function (root, factory) {
if (typeof define === 'function' && define.amd) {
define([], factory);
}
else if (typeof module === 'object' && module.exports) {
module.exports = factory();
}
else {
root.returnExports = factory();
}
}(typeof self !== 'undefined' ? self : this,
function () {
/** @type {SharedLib.PriorityQueueFactory} */
function priorityQueueFactory(comparator) {
const
push = function(queue, item) {
const
clonedQueue = queue.slice();
clonedQueue.push(item);
return clonedQueue.sort(comparator);
},
// ...
return {
push: push,
pop: pop
};
}
return priorityQueueFactory;
}));