Nessun risultato. Prova con un altro termine.
Guide
Notizie
Software
Tutorial
  • Lezione 30 di 45
  • livello principiante
Indice lezioni

Rdoc: introduzione e primo utilizzo

I principi del linguaggio di markup da utilizzare per la creazione della documentazione in Ruby con Rdoc
I principi del linguaggio di markup da utilizzare per la creazione della documentazione in Ruby con Rdoc
Link copiato negli appunti

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.

Figura 3: esempio di output di RdocEsempio di documentazione


Ti consigliamo anche