Каков правильный синтаксис JSDoc для локальной переменной?

Для такой функции...

function example() {
  var X = 100;

  ...

  var Y = 'abc';

  ...

  return Z;
}

Мне нужно объяснить назначение некоторых локальных переменных. Добавление подобного описания...

function example() {
  /**
   * @description - Need to explain the purpose of X here.
   */
  var X = 100;

  ...

  /**
   * @description - Need to explain the purpose of Y here.
   */
  var Y = 'abc';

  ...

  return Z;
}

...похоже, JS Doc v3.4.0 его не забирает.

Каков правильный синтаксис?

P.S. Некоторые из моих вариантов использования требуют многострочных комментариев.


javascript jsdoc jsdoc3
person Kirkland    schedule 01.08.2016    source источник
comment
в качестве примечания.. refactoring.guru/smells/comments   -  person YakovL    schedule 08.12.2018

Ответы (5)


arrow_upward
41
arrow_downward

Я обычно использую что-то вроде кода ниже в своих проектах.

function example() {
  /**
   * Need to explain the purpose of X here.
   * @type {number}
   */
  var X = 100;

  ...

  /**
   * Need to explain the purpose of Y here.
   * @type {string}
   */
  var Y = 'abc';

  ...

  return Z;
}
person mash    schedule 01.08.2016

arrow_upward
15
arrow_downward

один лайнер:

  /** @type {string} */
  var Y = 'abc';
person vitaliytv    schedule 11.01.2020
comment
При ответе на старый вопрос полезно объяснить, к какому новому аспекту вопроса относится ваш ответ. Этот ответ ничего не говорит о том, что было сказано в принятом ответе, и не указывает, изменилась ли ситуация с течением времени из-за выхода новых версий программного обеспечения. - person Jason Aller; 11.01.2020
comment
Это должно быть отмечено как правильный ответ. Чтобы ответить @vitaliytv и расширить ответ, да, похоже, документ JS расширил свою поддержку внутренних членов. Это работает для меня. - person viztastic; 08.06.2020

arrow_upward
7
arrow_downward

Кажется, что JS Docs игнорирует комментарии внутри «блока» (например, класс, функция и т. д.). Я старался...

@description
@inner
@instance
@member
@memberof
@name
@summary

...и другие. Мне не удалось заставить ни одного из них создать документацию. Во всех примерах JS Doc для подобных вещей используются обычные комментарии JS.

Я пришел к выводу, что для этого не существует официального синтаксиса JS Doc.

person Kirkland    schedule 05.08.2016

arrow_upward
4
arrow_downward

Лучшее, что сработало для меня:

/**
  * @name AssetAutoGenerationOption
  * @type {"all" | "master" | "off"}
  */
export type AssetAutoGenerationOption = "all" | "master" | "off";
person vljs    schedule 10.03.2020

arrow_upward
0
arrow_downward

Вы можете использовать:

/**
 * @function
 * @property {number} x - Need to explain the purpose of X here.
 * @property {number} y - Need to explain the purpose of Y here.
 * @returns {number} - Describe return value here (assumed number type for this example)
 */
function example() {
  var x
  var y = 'abc';
  return z;
}
person Zippy    schedule 30.06.2021