Как документально оформить вложенные свойства в JSDOC?

Question

Я делаю свой первый JS-плагин с открытым исходным кодом для NPM и хочу, чтобы он был хорошо документирован.

Но сгенерированная документация конструктора классов выглядит слишком большой и выходит за пределы моего экрана.

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: