dojo js bibliothèque + jsdoc -> comment documenter le code?

Question

J'aimerais vous demander comment les gars qui développent le dojo créent la documentation? A partir des builds nocturnes, vous pouvez obtenir les fichiers js non compressés avec tous les commentaires, et je suis sûr qu'il y a un script de documentation qui va générer du HTML ou du XML.

Je suppose qu'ils utilisent jsdoc comme cela peut être trouvé dans leur dossier utils, mais je n'ai aucune idée sur la façon de l'utiliser. La boîte à outils jsDoc utilise différentes notations /**commenting**/ que les fichiers dojo d'origine.

Merci pour votre aide

Answer 1

Tout cela est fait avec un analyseur PHP personnalisé et Drupal. Si vous regardez dans util/docscripts/README et util/jsdoc/INSTALL vous pouvez obtenir tous les détails sanglants sur la façon de générer les documents.

Il est différent de jsdoc-toolkit ou JSDoc (comme nous l'avons découvert). FWIW, J'utilise jsdoc-toolkit car il est beaucoup plus facile de générer du HTML statique et il y a beaucoup de documentation sur les tags sur la page de code google.

Aussi, juste pour être clair, je ne développe pas le dojo lui-même. Je l'utilise beaucoup au travail.

Answer 2

Le processus "dojo jsdoc" comporte deux parties. Il y a un analyseur, écrit en PHP, qui génère xml et/ou json de l'ensemble des espaces de noms listés (définis dans util/docscripts/modules, donc vous pouvez ajouter vos propres espaces de noms. php ") et une partie Drupal appelée" jsdoc "qui s'installe sous forme de module/plugin/drupal.

L'aspect de Drupal est juste la vue de base de Dojo de ces données. Un XSLT bien conçu ou quelque chose à parcourir sur le json et produire html fonctionnerait tout de même, mais aucun de ceux-ci ne sont fournis par défaut (aimerait une contribution!). Je craque moi-même de Drupal, bien qu'il fonctionne depuis longtemps sur api.dojotoolkit.org. L'analyseur doc est exposé afin que vous puissiez utiliser ses capacités d'inspection pour écrire votre propre sortie personnalisée. Je l'utilise pour générer le code Komodo .cix dans un fichier PHP [plutôt bâclé] util/docscripts/makeCix.php, qui récupère les informations trouvées dans un document XML conçu pour correspondre à la spécification. Cela pourrait être modifié pour générer n'importe quel type de sortie que vous avez choisi avec un peu finagling.

La syntaxe de la doc est tout défini sur la page des lignes directrices de style: http://dojotoolkit.org/reference-guide/developer/styleguide.html