dojo js library + jsdoc -> come documentare il codice?

Question

Mi piacerebbe chiederti come creano i dojo i ragazzi che creano la documentazione?

Da build notturne è possibile ottenere i file js non compressi con tutti i commenti, e sono sicuro che ci sia qualche tipo di script di documentazione che genererà qualche html o xml.

Suppongo che usino jsdoc in quanto questo può essere trovato nella loro cartella utils, ma non ho idea di come usarlo. Il toolkit jsDoc utilizza diverse notazioni /**commenting**/ rispetto ai file dojo originali.

Grazie per il vostro aiuto

Answer 1

è tutto fatto con un parser PHP personalizzato e Drupal. Se si guarda in util/docscripts/README e util/jsdoc/INSTALL è possibile ottenere tutti i dettagli cruenti su come generare i documenti.

È diverso da jsdoc-toolkit o JSDoc (come hai scoperto).

FWIW, sto usando jsdoc-toolkit in quanto è molto più facile generare HTML statico e c'è molta documentazione sui tag nella codepage di google.

Inoltre, per essere chiari, non sviluppo il dojo stesso. Lo uso solo molto al lavoro.

Answer 2

Ci sono due parti nel processo "dojo jsdoc". Esiste un parser, scritto in PHP, che genera xml e/o json dell'intero spazio dei nomi elencato (definito in util/docscripts/modules, quindi è possibile aggiungere i propri spazi dei nomi.Vengono generate le istruzioni di utilizzo in cima al file "generate". php ") e una parte di Drupal chiamata" jsdoc "che si installa come un modulo drupal/plugin/qualunque.

L'aspetto Drupal di questo è solo la visione base di Dojo di questi dati. Un XSLT ben congegnato o qualcosa per iterare su json e produrre html funzionerebbe allo stesso modo, sebbene nessuno di questi sia fornito di default (piacerebbe un contributo!). Mi sono allontanato dal Drupal, anche se è già in esecuzione su api.dojotoolkit.org da qualche tempo.

Il parser del documento è esposto in modo che sia possibile utilizzare le sue funzionalità di ispezione per scrivere anche il proprio output personalizzato. Lo uso per generare il completamento del codice .cix di Komodo in un file PHP [piuttosto sciatto] util/docscripts/makeCix.php, che scarica informazioni come trovate in un documento XML creato per adattarsi alle specifiche lì. Questo potrebbe essere modificato per generare qualsiasi tipo di output che hai scelto con un po 'di finishing.

La sintassi DOC è tutto definito sulla pagina guida stile: http://dojotoolkit.org/reference-guide/developer/styleguide.html