[英]Documenting the return of a javascript constructor with jsdoc
I have a javascript function that returns a constructor (see code sample below). 我有一个返回构造函数的javascript函数(参见下面的代码示例)。 How would I document this with the @returns tag of jsdoc.
我如何使用jsdoc的@returns标记来记录这一点。 It doesnt seem correct to do @returns {MyConstructor} because that implies I am returning an instance of "MyConstructor" rather than the constructor itself, right?
做@returns {MyConstructor}似乎没有道理,因为这意味着我正在返回“MyConstructor”的实例,而不是构造函数本身,对吧?
function MyConstructor() {
var self = this;
self.myFunction = function() {
return true;
};
self.getMyFunctionResult = function() {
return self.myFunction();
};
}
/**
* @returns {?} A constructor that will be instantiated
*/
function getConstructor() {
return MyConstructor;
}
var constructor = getConstructor();
var instance = new constructor();
You can check the types returned by your functions using: 您可以使用以下方法检查函数返回的类型:
console.log(typeof constructor, typeof instance); // function object
In the documentation it says: 在文档中它说:
/**
* Returns the sum of a and b
* @param {Number} a
* @param {Number} b
* @returns {Number} Sum of a and b
*/
function sum(a, b) {
return a + b;
}
http://usejsdoc.org/tags-returns.html http://usejsdoc.org/tags-returns.html
So in you example it would be: 所以在你的例子中它将是:
/**
* Returns the MyConstructor class
* @returns {Function} MyConstructor class
*/
function getConstructor() {
return MyConstructor;
}
Or if you are creating an instance of an Item: 或者,如果要创建Item的实例:
/**
* Returns an instance of the MyConstructor class
* @returns {Object} MyConstructor instance
*/
function getInstance() {
return new MyConstructor();
}
I do not think there is a way to use the brackets after @returns
to document returning a specific instance. 我不认为有一种方法可以在
@returns
之后使用括号来记录返回特定实例。 What goes in the brackets is interpreted as a type , always. 括号中的内容始终被解释为类型 。 This being said, there's a way to document that a specific instance of a type is being returned, by documenting the instance and using a link to the instance.
这就是说,有一种方法可以通过记录实例并使用指向实例的链接来记录返回类型的特定实例。 I've shortened the code in the question to the essentials necessary to illustrate:
我已经将问题中的代码缩短到了说明所需的基本要素:
/**
* @class
*/
function MyConstructor() {
}
/**
* @returns {Function} A constructor that will be instantiated. Always
* returns {@link MyConstructor}.
*/
function getConstructor() {
return MyConstructor;
}
It can also be done with other things than classes: 它也可以用除了类之外的其他东西来完成:
/**
* @public
*/
var foo = 1;
/**
* @returns {number} {@link foo}.
*/
function getFoo(){
return foo;
}
As far as I know, this is as good as it gets with jsdoc 3. 据我所知,这与jsdoc 3一样好。
Maybe little bit late, but I have problem to find proper answer for your question event today. 也许有点晚了,但我今天有问题为你的问题活动找到合适的答案。
When I try generate JSDoc automatically on WebStorm, this is what I get: 当我尝试在WebStorm上自动生成JSDoc时,这就是我得到的:
class Test {}
/**
*
* @return {Test}
* @constructor
*/
function getTestConstructor() {
return Test;
}
Return type definition is still strange, but constructor annotation may fulfill the purpose. 返回类型定义仍然很奇怪,但构造函数注释可能会达到目的。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.