¿Por qué jQuery no usa JSDoc?

Question

¿O ellos y simplemente no está en la fuente? Realmente me gustaría obtener algo que evite que js-doc-toolkit se vuelva loco cada vez que analiza jQuery. También significa que no puedo documentar correctamente cualquier código usando jQuery como una dependencia sin al menos poner algunos bloques js-doc repetitivos, que no documentan adecuadamente la estructura de jQuery. ¿Hay alguna solución común de la que no tenga conocimiento? He intentado googlear, por cierto.

Answer 1

Haré un tiro en la oscuridad aquí ya que no puedo hablar por el equipo jQuery de por qué I no usaría JSDoc. JSDoc, al menos la última vez que lo verifiqué, no tenía ninguna forma clara de admitir la sobrecarga de métodos (o el cambio de parámetros ... el nombre que quiera darle aquí) y jQuery usa esto por todos lados. Vamos a dar un ejemplo sencillo común con .animate():

.animate({ height: 5 }) 
.animate({ height: 5 }, 100) 
.animate({ height: 5 }, 100, "linear") 
.animate({ height: 5 }, 100, "linear", func) 
.animate({ height: 5 }, 100, func) 
.animate({ height: 5 }, func) 
.animate({ height: 5 }, { duration: 100, queue: false }) 
.animate({ height: 5 }, { duration: 100, easing: "linear" }) 
.animate({ height: 5 }, { duration: 100, easing: "linear", complete: func }) 

Todas estas son válidos, ya que parameter types are checked and shifted as needed para apoyar como cualquier escenarios de sobrecarga como sea posible ... esto sólo confunde el infierno fuera de jsdoc, no hay manera limpia para agregar estos parámetros opcionales a la documentación. Por favor corrígeme si esto ha cambiado, pero la última vez que miré (y probablemente la última vez que el equipo echó un vistazo) todavía era el caso.

Otra posible consideración es cómo se generan algunos métodos cuando se ejecuta jQuery, por ejemplo (uno de muchos), casi todos event handler shortcuts son generated in a loop comportamiento similar para otros métodos ... ¿cómo se documentarían estos? La generación de JSDoc simplemente no funciona bien aquí.

Answer 2

No sé por qué no añadir el comentario jsdoc pero los chicos Google Closure estar al nivel de una versión actualizada de los "voluntarios externos" que necesitan para el compilador de cierre con optimización avanzada

http://code.google.com/p/closure-compiler/source/browse/trunk/contrib/externs/jquery-1.6.js?r=1152

Answer 3

Si bien no puedo agregar nada más que otros no tengan con respecto a la pregunta original, puedo proporcionar un enlace a algo que PUEDE documentar automáticamente jQuery.

Lo hace ejecutándolo en un entorno de tiempo de ejecución y luego analizando los árboles resultantes. Al igual que JSDoc, utiliza un Rhino modificado. Está en su infancia, pero espero que esto sea útil para alguien. :)

https://bitbucket.org/nexj/njsdoc