[英]Documenting factories with JSDoc
In order to avoid using new
in my JavaScript code, I write factories to create objects. 为了避免在我的JavaScript代码中使用
new
,我编写工厂来创建对象。
I have tried many combinations and the one that gives me the most satisfactory result is the following: 我尝试了很多组合,给我最满意的结果如下:
/**
* 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;
}());
The problem with these comments is there is no document
object defined. 这些注释的问题是没有定义
document
对象。 Therefore, I can't reference this object in another object and I can't inherit its documentation when I extends this object. 因此,我无法在另一个对象中引用此对象,并且在扩展此对象时无法继承其文档。
What is the appropriate way to document this kind of object? 记录此类对象的适当方法是什么?
If I use the @typedef
tag, I get the static factory
method and the document
object properly documented but no id
method documentation is generated by JSDoc: 如果我使用
@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;
}());
My recommendation to you is to well define the exports on your module using @typedef to define the type and then annotate the module.exports = factory with @type {FactoryDefinition} 我的建议是使用@typedef定义类型,然后用@type {FactoryDefinition}注释module.exports = factory来很好地定义模块的导出。
/** @typedef {{ id: !string }} */
var DocumentDefinition;
/** @typedef {!function(!object):!DocumentDefinition} */
var FactoryDefinition;
/** @type {FactoryDefinition} */
module.exports = factory
I always use a @typedef
outside my module wrapper where I summarise the complete set of functions exposed by the module. 我总是在我的模块包装器外部使用
@typedef
在那里我总结了模块公开的完整功能集。 This is the only way I managed to get code completion in my WebStorm IDE and generate useful HTML documentation. 这是我在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;
}));
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.