javascript - 重用函数接口(interface)的 JSDoc

Question

我正在连接多个电子邮件工具并将它们的 API 抽象为一个通用的 sendEmail 函数，每个函数都具有相同的 params 和相同的 returns服务。这意味着对于每个电子邮件服务(Mailchimp、SendGrid...)，我必须编写一个具有相同 JSDoc 的函数，该 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 被解释为函数的返回类型，而不是整个函数定义。所以像下面这样的东西是行不通的。

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

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

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

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

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

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