Bene bene, qualche riga di Ruby l'abbiamo scritta... ora però è necessario renderla comprensibile anche ad altri!
Come vi dicevo, il mio cammino verso Ruby è stato fortemente influenzato dall'esigenza nata in azienda di utilizzare Ruby e Rails in produttività , già operativamente su un progetto. Di conseguenza, è fondamentale che tutti gli altri componenti del team che lavorano al progetto siano in grado di leggere facilmente il mio codice e, perché no, una sua documentazione realizzata appositamente da me.
Lo step successivo che mi sono trovato ad affrontare è stato quello di documentare le mie librerie. Ho già dedicato un post alla documentazione in Ruby, quello che vedremo oggi è su come usare Rdoc, ovvero Ruby Documentation System.
Devo dirlo... Non amo molto Rdoc! àˆ grezzo, limitato e decisamente poco standardizzato. Non esistono veri e propri tag come per phpDocumentor o Javadoc. Qualcosa si riesce comunque ad ottenere!
Partiamo dal principio e riprendiamo il nostro esempio del post precedente. Certo, sarà banale, ma è comunque un inizio!
Anzi no! Rendiamola un po' più didattica.
# Classe persona
class Person
DEFAULT_FIRST_NAME = 'Anonymous'
DEFAULT_LAST_NAME = 'Coward'
attr_accessor :first_name
attr_accessor :last_name
def initialize(first_name = DEFAULT_FIRST_NAME, last_name = DEFAULT_LAST_NAME)
@first_name = first_name
@last_name = last_name
end
def ciao()
puts "Ciao #{self.name()}"
end
def name(reverse = false)
return reverse ?
"#{@last_name} #{@first_name}" :
"#{@first_name} #{@last_name}"
end
end
Create una cartella di prova, ad esempio chiamata edit
lib
person.rb
Aprite la console (Prompt di DOS su Windows) e portatevi nella cartella edit
lib/
--all
rdoc --all lib/
L'output dovrebbe essere qualcosa del tipo
person.rb: c.. Generating HTML... Files: 1 Classes: 1 Modules: 0 Methods: 2 Elapsed: 0.121s
In caso di errore controllate che l'installazione di Ruby sia avvenuta con successo, che la cartella nella quale si trova l'eseguibile di Rdoc sia nel vostro percorso di inclusione delle librerie.
A questo punto rdoc avrà creato una nuova cartella doc
A dire il vero il risultato è deprimente ma c'era da aspettarselo, non è che la classe originale abbondasse di commenti. àˆ quindi necessario arricchire un po' il nostro file al fine di fornire dei commenti che possano essere interpretati nella generazione della documentazione.
Alla pagina di Rdoc
Sfruttando un po' di immaginazione e la sintassi messa a disposizione da Rdoc ecco come si presenta la classe riscritta. Per semplicità di lettura riporto un estratto, il contenuto completo della classe così come il risultato della libreria sono scaricabili liberamente
#
# = Person - A really simple person
#
# This file is part of Ruby Diary.
# See http://blog.html.it/archivi/2007/10/10/the-ruby-diary.php
# for further information.
#
# Package:: Person
# Author:: Simone Carletti <weppos@weppos.net>
# Copyright:: 2007 Simone Carletti
#
#--
# SVN: $Id: person.rb 166 2007-10-18 15:39:49Z carletti $
#++
#
# = Person
#
# This class represents a single person.
#
# This is just a really simple example,
# created for the 5th post of the Ruby Diary.
#
# == Basic Usage
#
# [...]
#
class Person
# default first name
DEFAULT_FIRST_NAME = 'Anonymous'
# default last name
DEFAULT_LAST_NAME = 'Coward'
# let user set and get first name
attr_accessor :first_name
# let user set and get last name
attr_accessor :last_name
#
# Initializes the person with given +first_name+ and +last_name+.
#
# Default values are stored in <em>DEFAULT_FIRST_NAME</em>
# and <em>DEFAULT_LAST_NAME</em> constants.
#
def initialize(first_name = DEFAULT_FIRST_NAME, last_name = DEFAULT_LAST_NAME)
@first_name = first_name
@last_name = last_name
end
# [...]
end
:stopdoc:
Text written here doens't show in the final HTML documentation.
:startdoc:
Vediamo insieme le parti essenziali.
- Il primo blocco di commento è il blocco che viene inserito quando si seleziona il frame Files Person
- Poiché io lavoro quasi sempre su repository, ho incluso l'ID del file del repository incluso tra la sintassi
#--#++:stopdoc::startdoc: - Il blocco che precede immediatamente la definizione della classe viene incluso nel frame Classes
Nella sezione Basic Usage - A seguire ho inserito un commento per ogni costante e per ogni metodo accessorio.
- Infine, ho commentato con un blocco ogni funzione. Il blocco che precede immediatamente la funzione viene inserito come documentazione della funzione.
Insomma, Rdoc non è il massimo (ad esempio non presenta tag per specificare i parametri delle funzioni, il lancio di eccezioni o metodi statici) tuttavia è sempre meglio di nulla! Ricordo che la libreria ed il risultato sono disponibili per il download
Con l'imminente Ruby 1.9 e l'avvicinarsi di Ruby 2.0 chissà che non arrivi anche qualche novità su questo lato... qualcuno ha qualche informazione in merito?
