Tengo una promesa de que estoy tratando de documentar usando JSDoc. Tiene tres tipos de resolución, string[] , Object[] y Object . Parece que hay varias formas sugeridas para documentar esto, pero parece que no puedo encontrar nada concreto.
https://github.com/jsdoc/jsdoc/issues/1197#issuecomment-312948746 parece sugerir algo como esto:
/** * The results of the DNS resolution request * @promise DNSResolve * @fufill {(string[]|Object[]|Object)} * @reject {Error} */ /** * Resolve a DNS record * * @returns {DNSResolve} The result */Nota: En este, estoy usando la respuesta a varios tipos como se sugiere aquí . ¿Cómo se documenta JSDoc con un tipo de parámetro mixto?
Sin embargo, esto no parece haberse implementado y no aparece en https://jsdoc.app/ . También parece muy hinchado y sin aliento.
Mi idea era seguir la idea de tipo de retorno de TypeScripts de
Promise<string[] | Object[] | Object>¿Hay algún tipo de estándar sobre cómo hacer esto o debería usar el esquema sugerido por el problema #1197?
El hilo que vinculaste tiene todas las respuestas que necesitas. Si encuentra que el primer enfoque es demasiado extenso, use el tipo de retorno de promesa abreviada:
/** * @returns {Promise<(string[]|object[]|object>} */Sin embargo, esto no parece haberse implementado y no aparece en https://jsdoc.app/ . También parece muy hinchado y sin aliento.
Eso es porque jsdoc.app está muy, muy desactualizado. También me di cuenta de esto, ya que muchas de las nuevas sintaxis abreviadas de JSDoc abreviadas para muchas cosas no están actualizadas en el sitio, pero funcionan bien en IDE como VSCode y Webstorm.
Por ejemplo, los documentos de @typedef no mencionan que hay una versión abreviada como /** @typedef {{ id: number, name: string }} */
Parece "inflado" porque es la versión de formulario completo que es adecuada si necesita agregar una descripción a todas sus partes, o si necesita documentar los tipos de rechazo (que la versión abreviada no admite). Si no necesita eso, la versión abreviada es lo que debe usar.
Además, tenga en cuenta que https://jsdoc.app/ es mantenido por el mismo repositorio/desarrollador que https://github.com/jsdoc/jsdoc , el mismo repositorio del problema que vinculó. Entonces, cualquier cosa que se diga en ese tema debe considerarse como verdad.
¿Hay algún tipo de estándar sobre cómo hacer esto o debería usar el esquema sugerido por el problema #1197?
Tanto la sintaxis abreviada como la completa deben considerarse estándar, y ninguna es mejor que la otra. Utilice el que se ajuste a sus necesidades. Herramienta correcta para el trabajo correcto.