Pregunta ¿Hay un estándar JSDoc?


Sé que hay varios sabores de JSDoc alrededor. Y parece que cada implementación de un analizador JSDoc reconoce su propio conjunto de etiquetas. Por ejemplo, considere las diferencias en las etiquetas entre http://usejsdoc.org/ y http://www.techrepublic.com/blog/programming-and-development/create-useful-relevant-javascript-documentation-with-jsdoc/451.

En este punto, estoy confundido. ¿Existe una implementación canónica de JSDoc o un conjunto ampliamente reconocido de etiquetas núcleo? Esta ahí mejor implementación de JSDoc?


EDITAR

Como se pregunta en el comentario siguiente, el motivo de esta pregunta es que necesito analizar los comentarios de JSDoc para utilizarlos con una herramienta que estamos creando. Ver esta pregunta ": ¿Hay algún analizador JSDoc de código abierto escrito en Javascript?

Me preocupa que tenga que pasar mi propio analizador, y si lo hago, necesito saber qué etiquetas necesitan soporte.

Pero, en un nivel más profundo, me preocupa que no haya especificaciones consistentes (o implementación de referencia). Esto hace que JSDoc se sienta un poco ad hoc para mí.


16
2017-08-07 18:14


origen


Respuestas:


La que creo que es la característica más completa es la utilizada por compilador de cierre de google 

Una de las mejores cosas sobre el uso del compilador de cierre de google es que hará una verificación de tipo de tus funciones que han sido marcadas con información de tipo.

Siento tu dolor, me ocupo de esto todo el día. Aquí hay un ejemplo de una característica no estándar que tengo que codificar / documentar. Ext-JS usos @cfg para documentar las propiedades para el objeto de inicialización que pasa a un widget. El IDE que uso, IntelliJ, usa JSDoc para proporcionar mejores sugerencias de código e incluso entiende el dialecto de Ext. Para la mayoría de las cosas, funciona bien. Sin embargo, muchas veces tengo que duplicar la documentación de alguna manera para hacer que mi IDE y la herramienta de doc. (Versión de jsdoc de Ext) lo entiendan, no muy SECO. Aquí hay un ejemplo:

...
/** 
 * @cfg {string} title // Ext-JS grabs the type from this line
 * @type string // My IDE grabs the type from this line
 */
 title: null // My IDE requires this line to recognize the cfg
             // as a property of the object even though all cfgs
             // are available in the object
...

5
2017-08-07 18:19



Yo también comparto tu dolor. Es molesto que esto no esté estandarizado. Aunque estoy de acuerdo con el Sr. Juan Mendes en que las características de Closure Compiler son las más completas (¡y probablemente las más increíbles!),

Siempre he pensado en la lista de etiquetas que se encuentra aquí http://code.google.com/p/jsdoc-toolkit/w/list como lo más cercano que tenemos a una especificación real. Puede que esté desactualizado, pero aún así podría estar más cerca de lo que muchos analizadores e IDE implementan, mucho más de lo que lo haría Closure Compiler.

Ver también Wikipedia para el mínimo de consenso sobre qué etiquetas deberían estar allí. http://en.wikipedia.org/wiki/JSDoc

Aunque si su producto es compatible con el sabor del compilador de cierre de JSDoc, eso lo acercará un paso más a convertirse en el estándar de facto. :RE


4
2017-08-27 23:02