如何在 JSDOC 的函数参数中记录可能的配置属性？

Question

如何在 JSDOC 的函数参数中记录可能的配置属性：

/**
 * N level expectimax AI.
 *
 * @param {object} cfg  config
 *   cfg.minimaxDepth  - limit for minimax search
 *   cfg.expectiDepth  - limit for expectimax search
 *   cfg.weightFn  - position weight function
 *
 * @constructor
 */
function expectimaxAI(brdEngine, cfg) { ... }

cfg.minimaxDepth (cfg.*) 参数使用哪个标记？

是否可以记录合成的aiCfg 类型并将其引用为：

 * @param {aiCfg} cfg  config

还是其他？

Answer 1

读完official JSDoc 2.x docs我做了一些hack：

/**
 * @name BlindWeightRandomCfg
 * @function
 * @param {number} left   weight
 * @param {number} right  weight
 * @param {number} up     weight
 * @param {number} down   weight
 */

并将不存在的功能称为：

/**
 * Blind weight random AI.
 *
 * @param {Board} brdEngine  board engine from board.js
 * @param {BlindWeightRandomCfg} cfg  configuration settings
 * @constructor
 */
 ai.BlindWeightRandom = function(brdEngine, cfg) { ... }

现在参数cfg - 可点击定义BlindWeightRandomCfg！

更新 JSDoc 2.x 的另一种可能性：

/**
 * @name BlindWeightRandomCfg
 * @namespace
 * @property {number} left   weight
 * @property {number} right  weight
 * @property {number} up     weight
 * @property {number} down   weight
 */

对于 JSDoc 3.x：

/**
  @typedef PropertiesHash
  @type {object}
  @property {string} id - an ID.
  @property {string} name - your name.
  @property {number} age - your age.
 */

/** @type {PropertiesHash} */
var props;

似乎@typedef 是一个解决方案。请see other variants和at official docs。