如何以可读的方式记录 JSDOC 中的嵌套属性？

Question

我正在为 NPM 制作我的第一个开源 JS 插件，并希望将其记录在案。

但是 class 构造函数生成的文档看起来太大了，超出了我的屏幕范围。

class Karaoke {

  /**
   * Magic happen here.
   * @constructor
   * @param   {HTMLElement} element  DOM HTML element that used as a Karaoke instance root element.
   * @param   {object}      options  Options for the Karaoke instance.
   * @param   {object[]}    options.tracks An array of tracks for the karaoke.
   * @param   {string}      options.tracks[].url Audio file URL.
   * @param   {string}      options.tracks[].bgImg Background image URL  for the current track.
   * @param   {object[]}    options.tracks[].lyrics An array of a track lyrics lines.
   * @param   {string}      options.tracks[].lyrics[].text The text of the lyrics line.
   * @param   {number}      options.tracks[].lyrics[].start The time in milliseconds when lyrics line playing must to begin.
   * @param   {number}      options.tracks[].lyrics[].duration The lyrics line playing duration in milliseconds.
   * @param   {object[]}    options.tracks[].lyrics[].keyframes An array of keyframes for the lyrics line CSS playing animation.
   * @param   {string}      options.tracks[].lyrics[].keyframes[].key A key for the lyrics line CSS playing animation.
   * @param   {number}      options.tracks[].lyrics[].keyframes[].value A value for lyrics line CSS playing animation.
   */
  constructor( element, options = {} ) {

我做错了什么？有什么方法可以让它更具可读性吗？

Answer 1

您可以利用 @typedef（类型定义）标签

/**
 * @typedef {Object} Keyframe
 * @property {string} key A key for the lyrics line CSS playing animation.
 * @property {number} value A value for lyrics line CSS playing animation.
 */

/**
 * @typedef {object} Lyric
 * @property {string}     text The text of the lyrics line.
 * @property {number}     start The time in milliseconds when lyrics line playing must to begin.
 * @property {number}     duration The lyrics line playing duration in milliseconds.
 * @property {Keyframe[]} keyframes An array of keyframes for the lyrics line CSS playing animation.
 */

/**
 * @typedef {object} Track
 * @property {string}  url An array of tracks for the karaoke.
 * @property {string}  bgImg Background image URL for the current track.
 * @property {Lyric[]} lyrics An array of a track lyrics lines.
 */

 /**
  * @typedef {object} Options
  * @property {Track[]} tracks An array of tracks for the karaoke.
  */

class Karaoke {
  /**
   * Magic happen here.
   * @constructor
   * @param {HTMLElement} element DOM HTML element that used as a Karaoke instance root element.
   * @param {Options}     options Options for the Karaoke instance.
   */
  constructor( element, options = {} ) {
  }
}

这将生成以下 HTML 文档：

当您点击 Options link:

如何以可读的方式记录 JSDOC 中的嵌套属性？

How to document nested properties in JSDOC in a readable way?

jsdoc