Ruby Diary #05: Generare documentazione con Rdoc

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!

# Classe persona
class Person
    def initialize(name = "Anonymous")
        @name = name
    end
    def ciao()
        puts "Ciao #{@name}"
    end
end

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. Ora create dentro una cartella lib e salvate la classe in un file person.rb. Dovrestre ora avere una struttura tipo questa.

Aprite la console (Prompt di DOS su Windows) e portatevi nella cartella edit appena creata. Ora lanciate rdoc dando come target lib/ e come opzione --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 con all'interno la documentazione della classe.

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 troverete tutto quello che serve per usare al meglio il tool. Chi già  utilizza Javadoc o phpDocumentor non avrà  fatica a comprendere l'uso di Rdoc e sono altrettanto convinto che presto lo troverà  molto "stretto"... almeno questa è la mia sensazione! Succede anche a voi?

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 della documentazione. In questo caso ho incluso qualche dettaglio sul file, identificando questa classe come parte del package Person.
• Poiché io lavoro quasi sempre su repository, ho incluso l'ID del file del repository incluso tra la sintassi #-- e #++. Questi due marcatori indicano a Rdoc di non analizzare il testo incluso all'intero. Stesso comportamento per :stopdoc: e :startdoc: al fondo del file.
• Il blocco che precede immediatamente la definizione della classe viene incluso nel frame Classes della documentazione. In questo caso ho incluso informazioni sulla documentazione, raggruppandole in sottosezioni.
  Nella sezione Basic Usage ho inserito anche degli esempi di codice. Se un blocco di testo rientra rispetto al margine della riga precedente, quest'ultimo viene analizzato come codice ed inserito nella documentazione con una formattazione specifica.
• 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?