[英]jsdoc @typedef - how to declare function properly?
这是我的 jsdoc 声明。
我应该如何调整它,以便MyNewType.logFirst
属性实际上引用我在下面注释的logFirst
function?
// my-new-type.js
/**
* MyNewType definition
* @typedef {Object} MyNewType
* @property {function} logFirst
* @property {function} logSecond
*/
/**
* @param {number} first
* @param {number} second
* @returns MyNewType
*/
module.exports = (first, second) => {
/**
* logs first argument
* @param {number} times
*/
function logFirst(times) {
for (let i = 0; i < times; i++) {
console.log(first);
}
}
/**
* logs second argument
* @param {number} times
*/
function logSecond(times) {
for (let i = 0; i < times; i++) {
console.log(second);
}
}
return {
logFirst,
logSecond
};
};
重要的是,我们保持这种“工厂”结构。
我希望我的 IDE 将MyNewType.logFirst
与logFirst
定义绑定。
除非我弄错了,否则我看不到赞成的解决方案是如何工作的。
JSDoc 中没有像@typedef {MyNewType} MyNewType
那样的东西,而是@typedef {Object} MyNewType
(定义基本类型)(参见文档)
此外,注释在给定的解决方案中都混在一起了。 例如,@ @param
仅用于函数参数和声明专用函数类型时(请参阅文档)
最后但并非最不重要的一点是,没有冒犯,但赞成的解决方案也是错误的,因为它混合了var MyNewType
类型声明(具有两个参数的函数并返回具有两个属性的对象)和实际返回值声明(所述的两个属性)目的)。 除了不包括返回类型周围所需的括号。
编辑:哦,我忘了logFirst
不是number
而是Function
,这是 OP 同事提出的解决方案中的另一个错误。
我真的无法理解为什么人们会赞成这样一个破碎的解决方案......
绝不是 JSDoc 的专家,但是我认为以下解决方案应该可以解决所有这些问题,对于新的 SO 访问者:
(注意:我不明白为什么我们需要两个不同的 typedef 用于 logFirst 和 logSecond 函数,因为它们具有完全相同的签名,但是 JFF 我指定了两者)
/**
* Declare our "logFirst" type (which is a function)
*
* @callback TypeFnLogFirst
* @param {number} times
* @returns {void}
*/
/**
* Declare our "logSecond" type (which is a function)
*
* @callback TypeFnLogSecond
* @param {number} times
* @returns {void}
*/
/**
* Declare our returned type
*
* @typedef {Object} TypeObjTwoFns
* @property {TypeFnLogFirst} logFirst
* @property {TypeFnLogSecond} logSecond
*/
/**
* Declare our "MyNewType" type (which is a function)
* with two parameters
* and a return value (object literal of type TypeObjTwoFns)
* (==> where the magic happens)
* Note that "[at]typedef Function" is the same as "[at]callback" (as per the docs)
*
* @typedef {Function} TypeFnNewType
* @param {*} first
* @param {*} second
* @returns {TypeObjTwoFns}
*/
/** @type {TypeFnNewType} MyNewType */
var MyNewType = (first, second) => {
/** @type {TypeFnLogFirst} logFirst */
function logFirst(times) {
for (let i = 0; i < times; i++) {
console.log(first);
}
}
/** @type {TypeFnLogSecond} logSecond */
function logSecond(times) {
for (let i = 0; i < times; i++) {
console.log(second);
}
}
return {
logFirst,
logSecond
};
};
以防万一它对任何人有帮助,因为 OP 是我的同事:
// my-new-type.js
/**
* MyNewType definition
* @typedef {MyNewType} MyNewType
* @param {number} first
* @param {number} second
* @property {function} logFirst
* @property {function} logSecond
* @returns MyNewType
*/
var MyNewType = module.exports = (first, second) => {
/**
* logs first argument
* @typedef {number} logFirst
* @param {number} times
*/
function logFirst(times) {
for (let i = 0; i < times; i++) {
console.log(first);
}
}
/**
* logs second argument
* @param {number} times
*/
function logSecond(times) {
for (let i = 0; i < times; i++) {
console.log(second);
}
}
return {
logFirst,
logSecond
};
};
这对我们来说效果很好。
仅当使用 Typescript作为类型检查器时,IMO 才有更简单的解决方案:
/** @typedef { (first: number, second: number) =>
{logFirst: (time: number) => void, logSecond: (time : number) =>
void}} MyNewType */
/** @type { MyNewType } */
var MyNewType = module.exports = (first, second) => {
...
}
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.