In questo e nei prossimi capitoli vedremo come rendere i nostri programmi pronti per essere distribuiti al mondo intero. Ci occuperemo della documentazione, del packaging e del building. Cominciamo a vedere uno degli aspetti, spesso snobbato, dell'intero ciclo di sviluppo: la documentazione. I principali strumenti che Ruby mette a disposizione per l'integrazione della documentazione all'interno del codice sono RDTool e RDoc. In questa guida faremo riferimento solo a RDoc, che è diventato lo standard, mentre RDTool sta diventando lentamente obsoleto.
RDoc permette di introdurre, utilizzando un semplice linguaggio di markup, la documentazione direttamente all'interno dei sorgenti. Vediamo innanzitutto quali elementi di formattazione sono disponibili. Vediamo un esempio con incluse tutte le necessarie spiegazioni:
=begin rdoc
All'inizio va inserito l'apposito tag che segna l'inizio dei commenti utilizzati da RDoc.
Si possono creare vari effetti, ad esempio le parole in *grassetto* vanno inserite tra due asterischi, quelle in _corsivo_ vanno tra due underscore e quelle +monospazio+ vanno scritte tra due più (+).
Per creare frasi in grassetto, corsivo e con carattere monospace vanno utilizzati rispettivamente i tag b, em e tt con le relative chiusure:
<b>Questa è una frase scritta in grassetto.</b> <em>Quest'altra invece è in corsivo,</em> <tt>ed infine una scritta con carattere monospazio.</tt>
Ci sono poi diversi tipi di liste, quelle con i classici punti
* primo elemento * secondo elemento
ci sono poi le liste numerate e quelle alfabetiche
1. primo elemento 2. secondo elemento a. primo elemento b. secondo elemento
Infine ci sono le liste che utilizzano delle etichette
[nome] Lev [cognome] Tolstoj
oppure
nome:: Lev cognome:: Tolstoj
Per le intestazioni sono disponibili più livelli
= Livello 1 == Livello 2 === Livello 3
e così via, aggiungendo degli "uguale" avremo livelli sempre inferiori.
Infine va messo il tag di chiusura
=end
Per generare la documentazione dall'esempio appena visto salviamolo in un file che chiamiamo esempio_rdoc.rb ed eseguiamo RDoc:
$ rdoc esempio_rdoc.rb
esempio_rdoc.rb:
Generating HTML...
Files: 1
Classes: 0
Modules: 0
Methods: 0
Elapsed: 0.108s
Questo comando creerà una directory doc contenente la documentazione relativa ai nostri sorgenti. In Figura 3 uno stralcio dell'output prodotto.
