JSDoc中的文档重载函数答案

【问题标题】：Document overloaded function in JSDocJSDoc中的文档重载函数
【发布时间】：2019-11-13 18:04:42
【问题描述】：

我有一个重载的 toggle 函数，想用 JSDoc 记录行为。

如果值已定义，则窗口状态设置为truthy 参数的布尔值，如果未定义，则窗口状态切换。我正在寻找这样的东西。

/**
 * Set the map window in mobile
 * @param {undefined|*} on - toggle or set the window state
 *  - {undefined} toggles window state
 *  - {*} set window state
 */
toggleWindow(on) {
  if (on === undefined) {
    on = !this.state.window;
  }
  this.setState({ mapWindow: !!on });
}

【问题讨论】：

与您的实际问题无关，但如果您将toggleWindow 作为不带参数的函数，然后将其他功能移至setWindow 之类的函数中，这似乎会更清楚。跨度>
默认值？ usejsdoc.org/…
@epascarello on=!this.state.window 不是一个坏主意，因为默认参数会在“调用时”重新评估即使它没有直接回答问题，但这样的答案应该会为您赢得一些支持.

标签： javascript jsdoc

【解决方案1】：

取自here：

您需要将每条评论的开头和结尾嵌套在一起，如下所示：

/**
 * DateRange class to store ranges and query dates.
 *
 * @constructor
 * @param {(Moment|Date)} start Start of interval
 * @param {(Moment|Date)} end End of interval
 *//**
 * DateRange class to store ranges and query dates.
 *
 * @constructor
 * @param {!Array} range Array containing start and end dates.
 *//**
 * DateRange class to store ranges and query dates.
 *
 * @constructor
 * @param {!String} range String formatted as an IS0 8601 time interval
 */
function DateRange(start, end) {
  // ...
}

但是请注意，构造函数重载没有组合在一起。每个重载仍会收到完整的成员列表，因此部分文档变得多余。不过，可能可以在模板中修复。

【讨论】：

【解决方案2】：

由于上一个答案对我不起作用。试试：

/** @type {((param: string) => boolean) & ((param: string, overloadedParam: string) => string))} */
const func = (param, overloadedParam) => { … }

请将此答案归功于 GitHub 上的 ExE-Boss，可在此处找到： https://github.com/microsoft/TypeScript/issues/25590#issuecomment-480022039

（这适用于标准 JS，以及 TS）

【讨论】：

它在标准 JS 中不起作用，因为香草 JSDoc 工具无法理解您正在使用的箭头函数语法，命令行 jsdoc 将无法解析它并生成一个错误。你写的是 TypeScript，只能在兼容 TS 的文档解析器中工作。