重用函数接口的 JSDoc

Question

我连接到多个电子邮件工具并将它们的 API 抽象为一个通用 sendEmail 函数，每个服务具有相同的 params 和相同的 returns。这意味着对于每个电子邮件服务（Mailchimp、SendGrid...），我必须编写一个函数，该函数具有相同的 JSDoc，描述相同的 @params 和相同的 @returns...

是否有有效的 JSDoc 语法来使用 @typedef 或类似函数，而不是在每个函数上方声明 @params 和 @returns，只需描述类型？

...不禁用 ESLint 的奖励积分 require-jsdoc

Answer 1

有一种方法可以定义它。使用 @callback 相当于 @typedef 的功能。

/**
 * @callback sendEmail
 * @param {string} to
 * @param {string} body
 * @returns {boolean} to indicate success or failure
 */

然后您可以使用 sendEmail 作为类型：

/**
 * @param {sendEmail} sender - function to send the email
 */
function createEmailService(sender) { ... }

问题是没有指定函数类型的好方法，因为函数上的 @type 被解释为函数的 return 类型，而不是整个函数定义.所以像下面这样的东西不起作用。

/**
 * @type {sendEmail}
 */
function mailchimpEmailSender(to, body) { ... }

您可以让它与以下内容一起使用，但这不是一个很好的解决方案。我还在寻找更好的解决方案。

/**
 * @type {sendEmail}
 */
let mailchimpEmailSender
mailchimpEmailSender = function(to, body) { ... }

更新： 我发现如果将函数声明包装在括号中，它似乎允许 @type 应用于变量而不是函数声明。

/**
 * @type {sendEmail}
 */
const mailchimpEmailSender = (function(to, body) { ... })

到目前为止，这是我最喜欢的解决方案，因为它允许您使用适当的变量声明关键字。唯一的缺点是它要求您记住添加并非绝对必要的代码。

重用函数接口的 JSDoc

JSDoc for reused Function interface

javascript

jsdoc

typescript

jsdoc3

typescript-typings