Comment indiquer que le paramètre est facultatif à l'aide de JSDoc en ligne?


119

Selon le wiki JSDoc pour @param, vous pouvez indiquer qu'un @param est facultatif en utilisant

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

et vous pouvez indiquer un paramètre en ligne en utilisant

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

Et je peux les combiner comme suit, ce qui fonctionne bien.

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

Mais j'aimerais savoir s'il existe un moyen de tout faire en ligne si possible.

Réponses:


123

De la documentation officielle :

Paramètre facultatif

Un paramètre facultatif nommé foo.

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

Un paramètre optionnel foo avec la valeur par défaut 1.

@param {number} [foo=1]

7
Je demandais comment le faire en ligne. L'exemple que vous donnez semble être le même que celui que j'ai montré dans ma question.
studgeek

67

Après quelques recherches, j'ai trouvé que ça allait aussi

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

Juste un peu plus attrayant visuellement que function test(/**String=*/arg) {}


9
Ceux-ci sont valides (et documentés dans l'aide de JSDoc), mais ils ne sont pas en ligne - ce que je recherchais.
studgeek

La question concerne la notation JSDoc en ligne. C'est une information intéressante, mais ne répond pas à la question
Ken Bellows

51

J'ai trouvé un moyen de le faire en utilisant des expressions de type Google Closure Compiler . Vous mettez un signe égal après le type comme ceci: function test(/**String=*/arg) {}


10
WebStorm / IntellIDEA prend en charge cette notation
Peter Aron Zentai

3
Oui, je pense donc que cela a été suffisamment accepté pour le marquer comme la réponse.
studgeek

4
@PeterAronZentai, j'ajouterai WebStorm / IntelliIDEA le prend en charge car j'ai mis une demande de fonctionnalité pour cela :). Ils prennent désormais en charge la majorité des expressions de type Google Closure Compiler, ce qui est excellent.
studgeek

1
Ne fonctionne pas pour moi pour un deuxième paramètre facultatif.
DaveWalley

3

Si vous utilisez des commentaires de type en ligne sur les arguments de fonction et que vous vous demandez comment marquer un argument de fonction comme facultatif dans cette notation, j'ai trouvé que le simple fait d'attribuer des valeurs par défaut aux arguments facultatifs fonctionnait. Si vous voulez que la valeur par défaut soit, undefinedvous devez également la définir explicitement, sinon l'argument ne sera pas marqué comme facultatif (même s'il est précédé d'arguments déjà facultatifs):

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

Si vous survolez demovotre IDE, vous devriez voir les deux optional1et optional2apparaître comme facultatifs maintenant. Dans VSCode qui est indiqué par ?après le nom de l'argument (notation TypeScript). Si vous supprimez = undefinedde optional2vous, vous ne verrez optional1qu'être facultatif, ce qui est bien sûr absurde, donc la valeur par défaut ici doit être explicite, comme je l'ai mentionné dans le paragraphe ci-dessus.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.