Oltre ai commenti scritti tra i tag visti prima, RDoc prende in considerazione anche i normali commenti scritti facendo iniziare la riga con il carattere #. Ovviamente l'utilità di un simile meccanismo sta nell'integrazione tra il codice e i commenti che con RDoc diventano anche documentazione. Per illustrare questa caratteristica andiamo a ripescare le nostre classi e aggiungiamoci i commenti. L'ultima versione era la seguente:
class Veicolo
attr_reader :carburante
def initialize (carburante)
@carburante = carburante
end
def rifornimento (quantita)
@carburante += quantita
end
end
class CarroArmato < Veicolo
attr_reader :colpi
def initialize (carburante, colpi)
super(carburante)
@colpi = colpi
end
end
class Camion < Veicolo
attr_reader :posti
def initialize (carburante, posti)
super(carburante)
@posti = posti
end
end
Commentiamole inserendo una descrizione generica per ogni classe, e poi descriviamo tutti gli attributi e tutti i metodi; il risultato finale sarà:
# Implementazione di un veicolo generico utilizzato # come superclasse per tutti gli altri veicoli. class Veicolo # quantità di carburante nel veicolo attr_reader :carburante # crea un nuovo veicolo con una determinata # quantità di carburante def initialize (carburante) @carburante = carburante end # rifornisce il veicolo di carburante def rifornimento (quantita) @carburante += quantita end end # Implementazione di un carro armato, # ha come superclasse Veicolo. class CarroArmato < Veicolo # numero di colpi presenti nel carro armato attr_reader :colpi # crea un nuovo carro armato con una data quantità # di carburante e di colpi def initialize (carburante, colpi) super(carburante) @colpi = colpi end end # Implementazione di un camion per il trasporto di soldati, # ha come superclasse Veicolo. class Camion < Veicolo # numero di posti presenti nel camion attr_reader :posti # crea un nuovo camion con una data quantità # di carburante e di posti def initialize (carburante, posti) super(carburante) @posti = posti end end
Salviamo tutto ed eseguiamo RDoc che, se chiamato senza argomenti, genera la documentazione per tutti i sorgenti Ruby e C (eventuali estensioni di Ruby) presenti nella directory corrente e nelle sue sotto-directory:
$ rdoc veicolo.rb
veicolo.rb: c..c.c.
Generating HTML...
Files: 1
Classes: 3
Modules: 0
Methods: 4
Elapsed: 0.176s
In Figura 4 vediamo la pagina di documentazione della classe Veicolo con in evidenza il pop-up del metodo rifornimento. I pop-up vengono chiamati attraverso i link collegati ai nomi dei metodi e mostrano i relativi stralci di codice.
In Figura 5 vediamo invece il codice come è generato da RDoc chiamato con le opzioni -NS che vedremo dopo.
