Jak zwrócić void w JsDoc?

81

Czy istnieje określony sposób zadeklarowania metody lub funkcji zwracającej void w JsDoc? Obecnie uważam, że voidjest to domyślna wartość zwracana, a inne wartości zwracane muszą być szczegółowo określone:

/**
 * @return {Integer} The identifier for ...
 */
javascript ide jsdoc Wieża
źródło
eslint.org/docs/rules/valid-jsdoc mówi @returns {void}Ahhh, ktoś już o tym wspomniał: stackoverflow.com/a/45450508/470749
Ryan

Odpowiedzi:

93

Nie sądzę, że musisz wybierać z zestawu typów w JsDoc ... możesz użyć dowolnej nazwy typu (nawiasy klamrowe wskazują, że jest to typ), więc możesz po prostu zrobić:

@return {Void}

Chociaż jest to prawdopodobnie bardziej poprawne w przypadku JavaScript:

@return {undefined}
David Tang
źródło
może być też @returns {void}?
hellboy,
8
@Eugene nullniekoniecznie jest tym samym, coundefined
BadHorsie,
6
@return {Void}rzuca ostrzeżenia inspekcji kodu w IntelliJ IDE @return {undefined}i @return {void}nie.
Shanimal
4
nullnigdy nie jest tym samym, co undefined. Kiedy coś jest zerowe, nadal jest zdefiniowane, ale bez wartości. Undefined jest, no, nieokreślone :-)
Magnus Eriksson
3
Specyfikacje Ecmascript zawierają listę typów języków. Wartość zwracana przez voidoperatora to undefined. Nazwa typu wartości undefinedto Undefined, mimo że jej typeof undefinedwynikiem jest "undefined". Nazwa Voidnie jest zdefiniowana w specyfikacjach Ecmascript.
Aaron Mansheim,
104

Kompilator zamknięcia

Zgodnie z dokumentacją Google Closure Compiler, jeśli nic nie jest zwracane, należy pominąć adnotację @return.

Jeśli nie ma wartości zwracanej, nie używaj tagu @return.

Źródło: https://developers.google.com/closure/compiler/docs/js-for-compiler#tags

jsdoc-toolkit

Jednak w dalszej dokumentacji stwierdza się również, że returnType i returnDescription są parametrami opcjonalnymi.

returnType - Opcjonalnie: typ zwracanej wartości.

returnDescription - Opcjonalnie: dowolny dodatkowy opis.

Źródło: https://code.google.com/p/jsdoc-toolkit/wiki/TagReturns

Podsumowanie

Możesz pominąć adnotację zwrotną lub dołączyć ją bez żadnych parametrów.

Brent Robinson
źródło
10
Ta odpowiedź jest w rzeczywistości lepsza niż zaakceptowana. Jeśli Twoja funkcja nie zwraca wyniku, nie powinieneś mówić, że zwraca, undefinedponieważ jest to już niejawne w JavaScript i może powodować zamieszanie u każdego, kto czyta Twoje dokumenty.
Lucio Paiva
2
Nie, nie zgadzam się i mówię, że to nie jest dobry pomysł. Kiedy czegoś brakuje, nie wiesz, czy było to zamierzone, czy nie. Mówiąc wprost o zwracanym typie, nawet jeśli undefinedzmuszasz się do określenia swojego zamiaru, dobrze jest to również przy czytaniu go później. Dla wyjaśnienia, nie mówię, że powinno się zawierać bezużyteczne oświadczenie JS, mówię, że powinno się zawsze zawierać @returnsinstrukcję JSDoc (jestem przeciwny bezużytecznemu kodowi, ale nie przeciwko „bezużytecznym” komentarzom).
Mörre
IMO to sens, aby określić typ zwracanej niezdefiniowany, czy jest możliwe, że funkcja lub metoda powraca jakąkolwiek inną wartość, w tym przypadku można dostać coś takiego:@returns {Array|undefined} - returns array if operation successful, otherwise returns undefined
GrayedFox
19

Patrząc na dokumenty ESlint, których używają @returns {void}

Źródło: http://eslint.org/docs/rules/valid-jsdoc

Ponieważ muszę zapewnić @returnsdla każdej funkcji, aby przejść testy w celu wypchnięcia kodu dla niektórych projektów, jest to wymagane w moim przypadku.

primetimejas
źródło
1

Jeśli chcesz głośno powiedzieć, że nic nie jest zwracane, możesz to powiedzieć w swobodnym opisie . Jest to przydatne do wyjaśnienia sytuacji, w których użytkownik może spodziewać się zwrotu czegoś. Oczywiście prawidłowe nazwanie funkcji i parametrów powinno same w sobie uwidocznić oczekiwany typ zwracanego wyniku, ale nie zawsze jest to możliwe.

/**
 * This is a funny function. Returns nothing.
 * @param {string} a joke.
 */
var funny = function (joke) {
  console.log(joke);
};
Akseli Palén
źródło