PHPDoc: documentare i metodi di una classe

Metodi e proprietà magiche

La documentazione di una classe da rendere pubblica dovrebbe sempre essere presente per permettere agli sviluppatori che ne vorranno beneficiare di poterne comprendere facilmente il funzionamento. In questo caso il compito è molto semplice dato che di base l'unica parte necessaria è la descrizione breve, che non dovrebbe mai mancare, mentre una descrizione più estesa è auspicabile dove abbia senso.

Se nella nostra classe facciamo uso dei metodi magici __get(), __set() e __call() sarà più complicato per un utilizzatore finale comprendere rapidamente che cosa si può aspettare, dato che per definizione una classe che utilizza questi metodi non dichiara esplicitamente il nome degli stessi. Per questo motivo possiamo avvalerci dei tag @property e @method.

Il tag @property inserito nel DocBlock principale della classe permette di indicare in maniera esplicita le proprietà non dichiarate, ma accessibili tramite i magic methods, che la classe stessa si aspetta di avere a disposizione. Ovviamente in questo caso non si richiede che vengano elencate tutte le proprietà accessibili (verrebbe meno lo scopo stesso del costrutto). La sintassi, molto semplice, è cosi composta: un tag property per ogni elemento da rendere esplicito, seguito tipo, nome e da una descrizione facoltativa dello scopo.

In maniera analoga il tag @method permette di dichiarare metodi non definiti ma invocabili tramite la funzione magic __call(). In questo caso la sintassi prevede, dopo il tag, il tipo di valore che viene restituito dal metodo, il suo nome e, tra parentesi tonde, l'elenco dei parametri attesi con i rispettivi tipi. Anche in questo caso è possibile aggiungere una descrizione facoltativa.

Se non si utilizzano i namespace, scelta oggi sconsigliata, è possibile indicare l'appartenenza di una classe ad un gruppo più ampio tramite il tag @package. Questo è applicabile all'intero file o alla singola classe, ma la prassi moderna richiede la dichiarazione di una sola classe per file, rendendo quindi superflua questa scelta.

Nel complesso la documentazione di una classe con metodi o proprietà magiche assomiglierà quindi a questa:

<php
namespace Utilities;
/**
 *  Classe di utilità .
 *
 *  La classe MyClass fornisce metodi di utilità  per la modifica delle stringhe e
 *  dei numeri interi.
 *
 *  @property string $name
 *  @property array  $childs Elementi figli della classe.
 *
 *  @method boolean isValid(string $value) La funzione controlla che il valore passato sia valido.
 *  @method int sum(int $a, int $b)
 */
class MyClass
{
    public function __get() {
        // ...
    }
    public function __set() {
        // ...
    }
    public function __call() {
        // ...
    }
}

Documentare correttamente un metodo o una funzione

PHPDoc tratta un metodo e una funzione nella stessa maniera e prevede un costrutto che ne permette una documentazione esaustiva. Per prima cosa anche in questo caso è consigliabile iniziare con la descrizione sintetica del metodo, eventualmente aggiungere quella prolissa e quindi indicare i tag.

I tag che non dovrebbero mai mancare sono @param, per indicare i parametri del metodo, e return per il valore restituito dallo stesso: entrambi possono essere omessi se la funzione non ha parametri o se non restituisce valori. Ovviamente il tag @param deve essere ripetuto tante volte quanti sono i parametri richiesti. Nella lezione precedente sono elencati i tipi validi.

Se all'interno di un metodo viene emessa un'eccezione è possibile indicarlo tramite il tag @throws che deve essere seguito dal nome di classe completo dell'eccezione lanciata. In linea teorica sarebbe possibile usare il tipo padre da cui l'eccezione deriva, ma è più corretto indicare quest'ultima. Nel caso di chiamate a funzioni che a loro volta possono emettere eccezioni è necessario aggiungere un tag @throws per ognuna di esse in modo che l'utilizzatore sappia quali eccezioni aspettare.

Sia le funzioni che i metodi pubblici sono accessibili dal codice estraneo alla libreria distribuita avendo una visibilità esterna universale, ma in alcuni casi questa è rivolta esclusivamente ad un utilizzo interno. Per definire un metodo che è stato pensato per essere invocato direttamente dall'utilizzatore della libreria è possibile usare il tag @api, in caso contrario il tag da usare è @internal.

La documentazione di un metodo assomiglierà al seguente esempio:

<php
class MyClass
{
    private $name;
    /**
     *  Restituisce il valore di $name.
     *
     *  Il valore di $name viene impostato automaticamente dalla classe
     *  servizio MyService, questo metodo permette di ottenere il valore impostato.
     *
     *  @api
     *  @return string
     */
    public function getName()
    {
        return $this->name;
    }
    /**
     *  Metodo interno per impostare il valore $name.
     *
     * @internal
     * @param int $name
     * @throws MyException
     * @return string
     */
    public function setName($name)
    {
        if ($name === null) {
            throws new MyException();
        }
        $this->name = $name;
    }
}

Attribuzione di proprietà

Se l'intenzione è quella di distribuire il codice è consigliabile specificare le informazioni sulla proprietà intellettuale tramite i tag:

Tag	Descrizione
@author	Permette di indicare l'autore con nome, cognome ed eventualmente indirizzo email.
@copyright	Permette di indicare in formato libero un copyright con l'anno di inizio e quello di fine dello sviluppo o del supporto.
@license	Richiede una licenza valida (LGPL, MIT..) e può essere utilizzato per specificare i termini di utilizzo della parte a cui fa riferimento.

Ognuno di questi tag può essere associato all'intero file, ad un classe o ad un metodo specifico. In questo modo è possibile tributare il giusto riconoscimento intellettuale all'autore di un frammento di codice che utilizziamo all'interno della nostra libreria (se per il codice che abbiamo utilizzato avevamo i diritti necessari).