Yahoo! User Interface Blog (YUIBlog)

Carlo Zottmann Tema di Dana per YUI Doc

Mi piace usare YUI Doc per tutte le mie esigenze di documentazione JavaScript. Ho scoperto che funziona bene per documentare JS plain vanilla o codice jQuery - non è solo per YUI basati su progetti.

Ero scettico in un primo momento, come tendo a scrivere più jQuery rispetto al codice YUI. E 'stata una piacevole sorpresa scoprire che YUI Doc facilmente integrabile nel mio flusso di lavoro, e potrebbe produrre la documentazione utile per le mie non-YUI progetti. Certo, ha delle aspettative nei confronti di un progetto, ecc struttura dei file, ma nessuna di queste aspettative sono Showstoppers per me. D'altra parte, è un sistema leggero e posso alzarmi e funzionante in poco tempo.

Avere uno strumento analizzare il codice sorgente e automagicamente costruire la documentazione di qualità per me è grande - non solo per la rapida la ricerca di chiamate di funzione, ecc tardi, per me è un valore aggiunto in due modi:

In primo luogo, documentare il mio codice in entrambi i casi per il mio bene - Sono probabilmente costretta a ri-visitare in pochi mesi e dovrei essere in grado di raccoglierla in fretta. Non avendo documentazione significa certa confusione nel futuro, che non è una impressione che voglio dare ai miei clienti.

In secondo luogo, la documentazione codice potrebbe essere un po 'un concetto astratto per un cliente: che posso dirle è lì, ma l'unico modo che posso "dimostrare" la mia richiesta è per sparare il mio editor e puntare il dito contro i blocchi di commento nel mio codice. Che in realtà non sembrano molto impressionante - nel peggiore dei casi sembrano una brutta copia di documentazione "corretta".

Eppure, sparare il mio browser e mostrando i commenti stessi analizzati ed elaborati da YUI Doc - pulito, frizzante, coerenti - ora che è codice professionale maldestro proprio lì, la gente.

(Se hai appena pensato "codice documentato in un wiki è così buono e meno di una seccatura", si prega di accettare la mia triste clap golf - perché non è.)

Purtroppo, io non sono un fan della pelle di base YUI Doc. Quando ho la mano su un pezzo di codice solidamente documentata ai miei clienti, voglio che si veda il codice solidamente documentata; a me, tema di default YUI Doc non brillano abbastanza.

Guardando in giro per i temi di ricambio che non è stato possibile trovare. Così poche settimane fa ho deciso di scrivere il mio - Dana . Ecco uno screenshot di esempio:

Come potete vedere sopra, ho generato il noto YUI docs API come un esempio. Ecco la documentazione originale YUI - ed è qui la documentazione stessa sportive il nuovo tema di Dana .

Trovo il secondo più piacevole alla vista - spero che siete d'accordo! Fare clic su un po 'intorno, controllare alcune delle documentazioni di classe per un più approfondito confronto, giocare con i filtri, si sentono sotto le plastiche di lusso ancora a buon mercato.

Finora, ho ricevuto un sacco di feedback positivi. I miei clienti apprezzano l'aspetto più pulito, e mi sento meglio sulla presentazione più professionale del lavoro che ho messo nei miei progetti, fino al markup generato.

Come è stato costruito

Ho iniziato a scrivere Dana buttando via ogni po 'di HTML all'interno dei modelli predefiniti YUI Doc, a partire da zero e la stratificazione mio markup proprio sulla cima dei blocchi fondamentali di YUI Doc Cheetah codice. (Cheetah è il motore di Python template utilizzato da YUI Doc. I # blocchi troverai nei modelli di contenere codice Python eseguito da Cheetah.)

Per essere onesti, cercando di capire cosa sta succedendo nei modelli non era una passeggiata nel parco - YUI Doc modelli non sono annotati, e ottenere orientato come un nuovo arrivato nel sistema ha richiesto del tempo. Quando ho avuto la sensazione ho capito la struttura e la logica Cheetah, ho svuotato il resto del markup, sostituendola con alcuni costrutti molto semplici, e costruito in cima a quello. Ci volle un po '.

Se pensate di scrivere i propri temi, io consiglierei sia utilizzando Dana main.tmpl come punto di partenza, o guardando il formattato correttamente originale main.tmpl . Bothan Molti sono morti per portare questo modello.

Io non sono un designer, io ho cercato di mantenere il look semplice e chiaro senza l'aggiunta di molte campane e fischietti.

Built-in Goodies

Ho preso la libertà di implementazione di un (IMHO) una migliore visualizzazione di oggetti del tipo dei parametri: se diversi parametri vengono passati come proprietà di un singolo oggetto, ma solo che oggetto verrà visualizzato come un parametro in prime colonne delle tabelle.

Per fare un esempio, diciamo che si sta documentando un metodo aspetta un oggetto di tipo parametro contenente tre proprietà:

 * @param obj.param1 {String} A string! * @param obj.param2 {Number} A number! * @param obj.param3 {Boolean} A boolean, surprisingly! 

Ecco come questo metodo verrà visualizzato nella documentazione prodotta:

Tema di Default: method( obj.param1, obj.param2, obj.param3 )
Dana tema: method( obj )

Per un esempio reale, vedere la documentazione per eventi YAHOO.widget.DataTable 's .

Trovo che questo trattamento rende l'output più conciso.

Requisiti

Dana richiede uno dei più tardi YUI Doc si basa , ad esempio, costruire 50 funziona bene - ma non funziona con YUI Doc 1.0.0b1.

Installazione / Utilizzo

Suppongo che tu hai YUI Doc installato e funzionante, a questo punto. Basta scaricare da Dana GitHub , scompattarlo, e dire yuidoc.py di usarlo tramite il -t/--template opzione.

Chiusura dei lavori

Dana è ancora un work in progress, ci sono alcuni problemi minori sinistra, per esempio con alcune HTML code blocchi che escono troppo ampio. Non si tratta di affrontare automatici per me, ma il vostro chilometraggio può variare.

Per quei lettori che, come me, arrivare a girare la testa l'idea di sostenere Markdown in YUI Doc come faccio io (suggerimento, suggerimento), controlla Mike West YUI Doc forcella che aggiunge esattamente questo. In attesa di una nuova originale versione YUI Doc, voglio dire. * Cough * ;)

Potrai trovare Dana su GitHub . Se sei così inclinato, è possibile scaricare l' ultima versione stabile, come zip / tgz , anche. Se si verificano errori, si prega di creare un biglietto .

Dana è dual-sotto licenza MIT e GNU GPL v2. E 'stato testato in Safari 5 (OSX), FF3.6 (OSX), IE8 (WinXP).

Trova le conversazioni: bloglines | technorati

Condividi ed estendere: Segnalibro con Del.icio.us | Digg it! | reddit!