Follow

Java aveva un lato positivo. C’era una cosa che mi piaceva: javadoc. Ovvero un sistema per generare automaticamente una dettagliata e affascinante pagina web con la descrizione e la documentazione di ogni parte di codice scritto basandosi su alcuni speciali commenti del codice.

Ma io non sono un programmatore Java (dio me ne scampi) ma, fra i molti linguaggi, mi diverto con il Python. Così ho cercato in lungo e in largo un sistema che svolgesse le stesse funzioni di Javadoc. E l’ho trovato.

Python dispone di molti tool del genere, quindi ne ho provati un po, fino a far ricadere la mia scelta su Ephydoc. Ephydoc non solo svolge tutte le funzioni di javadoc ma è molto più potente e versatile.

Innanzitutto per istallarlo, come ormai sappiamo, digitiamo dal terminale:

# apt-get install python-epydoc

A questo punto il programma è pronto per essere utilizzato. L’importante è commentare il nostro codice seguendo delle piccole cose a mente.

Innanzitutto epydoc sfrutta la docstring standard di Python. Dovete sapere che Python integra nativamente un piccolo sistema di documentazione nel codice. Infatti proviamo a scrivere una funzione in questo modo:

def codice_esatto(code):
    """
    Verifica se il codice inserito è corretto.
    """
    if codice=="4 8 15 16 23 42" :
        return true
    else :
        return false

Il testo racchiuso fra le triple virgolette è una stringa che descrive la funzione codice_esatto. Infatti digitando dall’interprete:

>>> print codice_esatto.__doc__

Ci viene restituito proprio il testo fra virgolette.

Epydoc sfrutta proprio questo testo per comporre la pagina web e inoltre è possibile aggiungere alcuni elementi di markup per rendere la documentazione più elegante.

Per una guida completa alla documentazione vi rimando alla pagina ufficiale del manuale di epydoc dove ci sono molti esempi di facile interpretazione. Qui di seguito aggiungo una serie di tag di frequente utilizzo:

• @param p: Descrizione del parametro p
• @type p: Tipo del parametro p
• @return: Descrizione del valore restituito.
• @rtype: Tipo del valore restituito.
• @raise e: Descrizione sulle circostanze in cui viene lanciata l’eccezione e

Per il resto rimando sempre al sito ufficiale.

Una volta che abbiamo commentato tutti i nostri file (dovrebbero essere già commentati. Se non lo sono aih aih aih, è la regol aprima del programmatore) non ci resta che lanciare epydoc con:

epydoc file1.py file2.py ... fileN.py

Alla fine troveremo tutta la nostra documentazione nella cartella html. Buona lettura 🙂