Jak wskazać, że parametr jest opcjonalny, używając wbudowanego JSDoc?

119

Zgodnie z wiki JSDoc dla @param możesz wskazać, że @param jest opcjonalne, używając 

/**
    @param {String} [name]
*/
function getPerson(name) {
}

i możesz wskazać parametr w tekście, używając

function getPerson(/**String*/ name) {
}

I mogę je łączyć w następujący sposób, co działa dobrze.

/**
    @param [name]
*/
function getPerson(/**String*/name) {
}

Ale chciałbym wiedzieć, czy jest sposób, aby zrobić to wszystko w linii, jeśli to możliwe.

javascript google-closure-compiler jsdoc studgeek
źródło

Odpowiedzi:

123

Z oficjalnej dokumentacji :

Opcjonalny parametr

Opcjonalny parametr o nazwie foo.

@param {number} [foo]
// or:
@param {number=} foo

Opcjonalny parametr foo z wartością domyślną 1.

@param {number} [foo=1]
czerny
źródło
7
Pytałem, jak to zrobić na bieżąco. Podany przez ciebie przykład wydaje się być tym samym, co pokazałem w moim pytaniu.
studgeek
67

Po pewnym odkopaniu stwierdziłem, że te również są w porządku

/**
 * @param {MyClass|undefined}
 * @param {MyClass=}
 * @param {String} [accessLevel="author"] The user accessLevel is optional.
 * @param {String} [accessLevel] The user accessLevel is optional.
 */

Tylko nieco bardziej atrakcyjny wizualnie niż function test(/**String=*/arg) {}

vvMINOvv
źródło
9
Są one ważne (i udokumentowane w pomocy JSDoc), ale nie są wbudowane - tego właśnie szukałem.
studgeek
Pytanie dotyczy wbudowanej notacji JSDoc. To ciekawa informacja, ale nie odpowiada na pytanie
Ken Bellows
51

Znalazłem sposób, aby to zrobić, używając wyrażeń typu Google Closure Compiler . Po takim typie umieszczasz znak równości: function test(/**String=*/arg) {}

studgeek
źródło
10
WebStorm / IntellIDEA obsługuje ten zapis
Peter Aron Zentai
3
Tak, więc myślę, że zyskał wystarczającą akceptację, aby oznaczyć to jako odpowiedź.
studgeek
4
@PeterAronZentai, dodam WebStorm / IntelliIDEA obsługuje to w wyniku umieszczenia przeze mnie żądania funkcji :). Obsługują teraz większość wyrażeń typu Google Closure Compiler, co jest świetne.
studgeek
1
Nie działa dla mnie opcjonalny drugi parametr.
DaveWalley
1
popraw link; prowadzi do strony 404
chharvey
3

Jeśli używasz komentarzy typu inline do argumentów funkcji i zastanawiasz się, jak oznaczyć argument funkcji jako opcjonalny w tej notacji, stwierdziłem, że po prostu przypisanie wartości domyślnych do opcjonalnych argumentów zadziałało. Jeśli chcesz, aby wartość domyślna była taka undefined, musisz ustawić ją również jawnie, w przeciwnym razie argument nie zostanie oznaczony jako opcjonalny (nawet jeśli był poprzedzony już opcjonalnymi argumentami):

function demo(
  /** @type {String} */ mandatory,
  /** @type {Number} */ optional1 = 0,
  /** @type {Number} optional2 = undefined,
)

Jeśli najedziesz kursorem na demoswoje IDE, powinieneś zobaczyć zarówno optional1ioptional2 pojawić się jako opcjonalne teraz. W VSCode jest to oznaczone ?po nazwie argumentu (notacja TypeScript). Jeśli usuniesz = undefinedz optional2siebie, zobaczysz tylko optional1bycie opcjonalnym, co jest oczywiście nonsensem, więc wartość domyślna tutaj musi być wyraźna, jak wspomniałem w powyższym akapicie.

Tomáš Hübelbauer
źródło