jsdoc - 记录嵌套数组参数

Question

我正在尝试使用 jsdoc 来记录函数参数。传入一个包含 n 个对象的数组（routes）。每个对象都有一个 sequences 属性，该属性接受一个数组，该数组又包含 n 个具有一组属性的对象。函数的调用如下例所示：

myFunction(
  [
    {
      isClickable: true,
      isSelected: false,
      popupTitle: 'Route Biel/Bienne >> Freiburg/Fribourg',
      popupContent: ['Von: Biel/Bienne', 'Nach: Freiburg/Fribourg'],
      sequences: [
        {
          latLonTo: [46.68848, 7.68974],
          latLonFrom: [46.94691, 7.44079],
          mot: 'rail',
        },
      ],
    },
    {
      isClickable: true,
      isSelected: false,
      popupTitle: 'Route Bern >> Freiburg/Fribourg',
      popupContent: ['Von: Bern', 'Nach: Freiburg/Fribourg'],
      sequences: [
        {
          uicFrom: 8507150,
          uicTo: 8545100,
          mot: 'bus',
        },
      ],
    }
  ]
)

我的文档如下：

 /**
   * Load routes based on a given configuration.
   * @param {Object[]} routes Routes.
   * @param {boolean} routes[].isSelected If true, the route is
   *   selected initially.
   * @param {boolean} routes[].isClickable If true, the route can be
   *   selected or unselected by click.
   * @param {Object[]} routes[].sequences Route sequences.
   * @param {number} routes[].sequences[].uicFrom UIC number of start station.
   * @param {number} routes[].sequences[].uicTo UIC number of end station.
   * @param {array} routes[].sequences[].latLonFrom Lat/Lon coordinate array of start location
   *  (to be used if uicFrom not provided).
   * @param {array} routes[].sequences[].latLonTo Lat/Lon coordinate array of end location
   *  (to be used if uicTo not provided).
   * @param {string} routes[].sequences[].mot Method of transportation.
   *   Allowed values are "rail", "bus", "tram", "subway", "gondola",
   *   "funicular" and "ferry"
   * @returns {Promise<Feature[]>} Promise resolving OpenLayers features.
   */

结果不如预期，如下图所示：

如图红色所示，多维/嵌套sequence数组中的参数没有被jsdoc正确解析。在第二个括号之前，字符串的其余部分被添加到 description 列而不是 name 列。正确的输出应该是：

有谁知道如何做到这一点？我也对其他可能更正确的使用 jsdoc 的方法持开放态度。

非常感谢您的帮助

Answer 1

我会使用两个@typedef 注释：

• 路线
• 序列

/**
 * @typedef {Object} Sequence
 * @property {Array<number>} latLonTo
 * @property {Array<number>} latLonFrom
 * @property {string} mot
 */

/**
 * @typedef {Object} Route
 * @property isClickable {boolean}
 * @property isSelected {boolean}
 * @property popupTitle {string}
 * @property popupContent {Array<string>}
 * @property sequences {Array<Sequence>}
 */

/**
 * @param {Array<Route>} routes
 */
const func = routes => 42;

生成以下文档：