用于重用函数接口的 JSDoc答案

【问题标题】：JSDoc for reused Function interface用于重用函数接口的 JSDoc
【发布时间】：2019-07-31 20:02:35
【问题描述】：

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

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

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

【问题讨论】：

标签： javascript typescript typescript-typings jsdoc jsdoc3

【解决方案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) { ... })

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

【讨论】：