Как вернуть void в JsDoc?

81

Есть ли указанный способ объявить метод или функцию для возврата void в JsDoc? В настоящее время я считаю, что voidэто возвращаемое значение по умолчанию, и другие возвращаемые значения должны быть указаны специально:

/**
 * @return {Integer} The identifier for ...
 */
Башня
источник
eslint.org/docs/rules/valid-jsdoc говорит, @returns {void}что кто-то уже упоминал об этом: stackoverflow.com/a/45450508/470749
Райан

Ответы:

93

Я не верю, что вам нужно выбирать из набора типов в JsDoc ... вы можете использовать любое имя типа, которое хотите (фигурные скобки указывают на тип), поэтому вы можете просто сделать:

@return {Void}

Хотя, наверное, для JavaScript это правильнее:

@return {undefined}
Дэвид Танг
источник
может быть тоже @returns {void}?
hellboy
8
@Eugene nullне обязательно совпадаетundefined
BadHorsie
6
@return {Void}выдает предупреждение о проверке кода в IntelliJ IDE @return {undefined}и @return {void}не работает.
Shanimal
4
nullникогда не то же самое, что undefined. Когда что-то имеет значение NULL, оно все еще определено, но не имеет значения. Неопределенный, ну, ну, не определенный :-)
Магнус Эрикссон
3
В спецификациях Ecmascript перечислены типы языков. Значение , возвращаемое voidоператором является undefined. Название типа значения undefinedесть Undefined, даже если имеет typeof undefinedзначение "undefined". Имя Voidне определено в спецификациях Ecmascript.
Аарон Мансхайм
104

Компилятор закрытия

Согласно документации компилятора Google Closure, если ничего не возвращается, аннотацию @return следует опустить.

Если возвращаемого значения нет, не используйте тег @return.

Источник: https://developers.google.com/closure/compiler/docs/js-for-compiler#tags

jsdoc-toolkit

Однако в дальнейшей документации также указано, что returnType и returnDescription являются необязательными параметрами.

returnType - Необязательно: тип возвращаемого значения.

returnDescription - Необязательно: любое дополнительное описание.

Источник: https://code.google.com/p/jsdoc-toolkit/wiki/TagReturns

Резюме

Вы можете либо опустить аннотацию возврата, либо включить ее без каких-либо параметров.

Брент Робинсон
источник
10
Этот ответ на самом деле лучше принятого. Если ваша функция не возвращает результат, вы не должны говорить, что она возвращается, undefinedпоскольку это уже подразумевается в Javascript и может вызвать путаницу у тех, кто читает ваши документы.
Lucio Paiva
2
Нет, я не согласен и считаю, что это плохая идея. Когда чего-то не хватает, вы не знаете, было это намеренно или нет. Явное указание типа возвращаемого значения, даже когда undefinedвы заставляете себя заявить о своем намерении, также полезно при его прочтении позже. Чтобы прояснить ситуацию, я не говорю, что нужно включать бесполезный оператор JS, я говорю, что всегда следует включать оператор JSDoc @returns(я против бесполезного кода, но не против «бесполезных» комментариев).
Mörre
IMO имеет смысл указать тип возвращаемого значения undefined, если возможно, что ваша функция или метод вернет любое другое значение, и в этом случае вы получите что-то вроде этого:@returns {Array|undefined} - returns array if operation successful, otherwise returns undefined
GrayedFox
19

Глядя на используемые ими документы ESlint @returns {void}

Источник: http://eslint.org/docs/rules/valid-jsdoc

Поскольку мне нужно предоставить @returnsкаждой функции для прохождения тестов, чтобы отправить код для определенных проектов, это требуется в моем случае.

прайм-таймджас
источник
1

Если вам нужно сказать вслух, что ничего не возвращается, вы можете указать это в описании в свободной форме . Это полезно для прояснения ситуаций, когда пользователь может ожидать, что что-то будет возвращено. Конечно, только правильное имя функции и параметров должно сделать очевидным ожидаемый тип возвращаемого значения, но это не всегда возможно.

/**
 * This is a funny function. Returns nothing.
 * @param {string} a joke.
 */
var funny = function (joke) {
  console.log(joke);
};
Аксели Пален
источник