Pourquoi jQuery n'utilise-t-il pas JSDoc?

Question

Ou est-ce qu'ils ne sont pas à la source? J'aimerais vraiment avoir quelque chose qui empêchera js-doc-toolkit de paniquer à chaque fois qu'il analyse jQuery. Cela signifie également que je ne peux pas documenter correctement un code utilisant jQuery comme une dépendance sans au moins mettre des blocs js-doc standard, qui ne parviennent pas à documenter correctement la structure de jQuery. Y a-t-il une solution commune que je ne connais pas? J'ai essayé googling, btw.

Answer 1

Je vais prendre une photo dans le noir ici car je ne peux pas parler pour l'équipe de jQuery pourquoi I n'utiliserait pas JSDoc. JSDoc, au moins la dernière fois que j'ai vérifié, n'avait aucun moyen propre de supporter la surcharge de méthode (ou le changement de paramètre ... quel que soit le nom que vous vouliez lui donner ici) et jQuery l'utilise partout. Prenons un exemple simple commun avec .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 }) 

Tous ces éléments sont valables, car parameter types are checked and shifted as needed pour soutenir que tous les scénarios de surcharge possible ... ce embrouille tout l'enfer hors de JSDoc, il n'y a aucun moyen propre pour ajouter ces paramètres optionnels à la documentation. Veuillez me corriger si cela a changé, mais la dernière fois que j'ai regardé (et probablement la dernière fois que l'équipe a jeté un coup d'oeil) c'était toujours le cas. Une autre considération potentielle est de savoir comment certaines méthodes sont générées lorsque jQuery s'exécute, par exemple (une parmi beaucoup d'autres), presque tous les generated in a loop comportement generated in a loop similaire pour les autres méthodes ... comment les documenter? La génération JSDoc ne fonctionne vraiment pas bien ici.

Answer 2

Je ne sais pas pourquoi ils ne correspondent pas le commentaire de JSDoc mais les gars de fermeture Google semblent conserver une version mise à jour des « externs » dont ils ont besoin pour le compilateur de fermeture avec optimisation avancée

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

Answer 3

Bien que je ne puisse rien ajouter d'autre que la question originale, je peux fournir un lien vers quelque chose qui PEUT documenter automatiquement jQuery. Il le fait en l'exécutant dans un environnement d'exécution, puis en analysant les arbres résultants. Comme JSDoc, il utilise un Rhino modifié. C'est à ses balbutiements mais j'espère que c'est utile pour quelqu'un. :)

https://bitbucket.org/nexj/njsdoc