¿Cómo indicar que param es opcional usando JSDoc en línea?

119

De acuerdo con la wiki de JSDoc para @param , puede indicar que un @param es opcional usando 

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

y puede indicar un parámetro en línea usando

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

Y puedo combinarlos como el siguiente, que funciona bien.

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

Pero me gustaría saber si hay una manera de hacerlo todo en línea si es posible.

javascript google-closure-compiler jsdoc studgeek
fuente

Respuestas:

123

De documentación oficial :

Parámetro opcional

Un parámetro opcional llamado foo.

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

Un parámetro opcional foo con valor predeterminado 1.

@param {number} [foo=1]
czerny
fuente
7
Estaba preguntando cómo hacerlo en línea. El ejemplo que proporciona parece ser el mismo que mostré en mi pregunta.
studgeek
67

Después de investigar un poco, descubrí que también están bien

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

Solo un poco más atractivo visualmente que function test(/**String=*/arg) {}

vvMINOvv
fuente
9
Esos son válidos (y están documentados en la ayuda de JSDoc), pero no están en línea , que es lo que estaba buscando.
studgeek
La pregunta trata sobre la notación JSDoc en línea. Esta es información interesante, pero no responde a la pregunta
Ken Bellows
51

Encontré una manera de hacer esto usando expresiones de tipo Google Closure Compiler . Pones un signo igual después del tipo así: function test(/**String=*/arg) {}

studgeek
fuente
10
WebStorm / IntellIDEA admite esta notación
Peter Aron Zentai
3
Sí, creo que ha ganado suficiente aceptación como para marcarlo como la respuesta.
studgeek
4
@PeterAronZentai, agregaré WebStorm / IntelliIDEA lo admite como resultado de que puse una solicitud de función para él :). Ahora admiten la mayoría de las expresiones de tipo Google Closure Compiler, lo cual es genial.
studgeek
1
No me funciona para un segundo parámetro opcional.
DaveWalley
1
por favor arregle el enlace; conduce a una página 404
chharvey
3

En caso de que esté utilizando comentarios de tipo en línea en argumentos de función y se pregunte cómo marcar un argumento de función como opcional en esa notación, descubrí que simplemente asignar valores predeterminados a los argumentos opcionales funcionaba. Sin embargo, si desea que el valor predeterminado sea undefined, debe establecerlo explícitamente también; de lo contrario, el argumento no se marcará como opcional (incluso si está precedido por argumentos ya opcionales):

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

Si pasa el cursor sobre demosu IDE, debería ver ambos optional1y optional2aparecer como opcional ahora. En VSCode que se indica ?después del nombre del argumento (notación TypeScript). Si elimina = undefinedde optional2, verá que solo optional1es opcional, lo cual, por supuesto, no tiene sentido, por lo que el valor predeterminado aquí debe ser explícito, como mencioné en el párrafo anterior.

Tomáš Hübelbauer
fuente