Ruby Diary #03: A caccia di documentazione

La documentazione è fondamentale per un linguaggio tanto quanto per le sue librerie ed i programmi distribuiti. Ho già  speso qualche parola su fonti e risorse per Ruby e Rails nel mio post introduttivo ma, prima di andare avanti, vorrei spenderne ancora un paio sulla lettura della documentazione ufficiale delle librerie core di Ruby.

Ruby, lo vedremo più avanti, è un linguaggio completamente ad oggetti.
Questo significa che, in linea generale, ogni chiamata ad un metodo avviene su un'istanza di un oggetto o su una classe (metodi statici). Ma quali chiamate sono disponibili? Ad esempio, come posso stampare a video un oggetto? Quali azioni posso eseguire su una stringa?

A queste (e molte altre) domande troverete risposta nella documentazione di Ruby.

Quando ho aperto per la prima volta questo indirizzo mi sono chiesto: e mo', da che parte comincio? L'organizzazione delle informazioni assomiglia molto a Javadoc, dunque ero agevolato.

La distribuzione predefinita di Ruby prevede due gruppi di classi: Core Library e Standard Library.

La prima definisce le classi base che rappresentano i tipi di dato, kernel, classi e moduli. La seconda include classi e moduli utili alla maggior parte delle attività  in Ruby, come ad esempio l'oggetto URI, la libreria Net per interagire con connessioni di rete o CGI, per comunicare con il web.

Siccome questi due indirizzi diventeranno i vostri due migliori amici nel vostro futuro da sviluppatore Ruby è bene che abbiate le idee molto chiare su come interpretare le informazioni.

La pagina è suddivisa in due parti. Quella superiore, a sua volta, è composta da tre frame.

Il primo elenca i file disponibili nella libreria. Nella maggior parte dei casi si tratta di file con estensione .rb che indica l'uso di Ruby, ma potreste anche trovare file .c ad indicare che quel file è stato scritto in un linguaggio basato su C.

Il box Classes indica invece l'elenco delle classi e dei moduli disponibili nei file che compongono la libreria. I nomi possono essere semplici come Abbrev oppure contenere namespace come ACL::ACLList.

L'ultimo box elenca i metodi disponibili nella libreria corrente. A fianco di ogni metodo è disponibile, tra parentesi, il nome della classe che integra questo metodo. Questo perché, come potete vedere, uno stesso metodo può essere parte di più classi.

% (String)
% (Complex)
% (Float)
% (Bignum)
% (Fixnum)
% (Rational)

Nell'esempio sopra il metodo % appartiene a 6 classi differenti.
Ma... qualcosa non quadra... da quando % è un metodo?!? Era un operatore...

Eh no! Siccome ogni elemento in Ruby è un oggetto, stringhe e numeri compresi, anche gli operatori sono metodi! Non vi viene già  in mente qualche interessante possibilità ?

Il frame centrale presenta il reale contenuto della pagina, a seconda della selezione. Se si sceglie una classe viene presentata la descrizione dell'oggetto, i metodi che implementa, i moduli che include e quante più informazioni possono essere utili al programmatore.

Se si seleziona un metodo viene presentata la pagina della classe che lo implementa con il focus sui dettagli del metodo come argomenti che accetta, valori restituiti ed esempi.

Carino? Non solo, utile! Prendete confidenza con questa interfaccia perché non mancherà  molto alla necessità  di cominciare a documentare le vostre classi!

Non è tutto oro quello che luccica. I programmatori più esigenti si accorgeranno presto che questa documentazione pecca rispetto ad alcuni punti fondamentali in confronto ad altri linguaggi, come JavaDoc per Java o phpDoc per PHP. Ad esempio, immaginate questo caso:

class BaseClass
    def my_method()
    end
end
class MyClass < BaseClass
end

MyClass estende BaseClass dunque ne eredita metodi e variabili. Tuttavia se creerete la documentazione di MyClass quest'ultima non avrà  alcun riferimento ai metodi ereditati dai genitori ma solo a quelli definiti direttamente nell'oggetto. Decisamente poco utile!

Ma non è tutto. A differenza di Java e PHP, Ruby non offre un set completo di etichette come @thrown, @return, @param, @static... e questo rende la documentazione meno accurata.

Al momento non ho individuato altri problemi degni di nota. Ovviamente i commenti sono aperti. Come trovate la documentazione di Ruby? Semplifichereste o migliorereste qualcosa?