Corretto modo di documentare la classe in Netbeans PHP

Question

Per motivi di facilità di manutenzione E completamento automatico della classe IDE e accenno ai membri, ho usato PHPDoc nel mio progetto. Dato questo esempio di classe:

class my_class { 
    public $id; 
    public $name; 
    public $number; 

    public function __construct() { 
     //Do something 
    } 

    public function Rename($name) { 
     $this->name = $name; 
    } 
} 

io preferirei di documentare tutte le proprietà ($id, $name e $number) con la documentazione di classe stessa, che è al di sopra della dichiarazione di classe, e quindi inserire la documentazione per i metodi (se necessario) di cui sopra ogni metodo Ecco quello che in ultima analisi, voglio la mia classe a guardare come:

/** 
* Represents an example class for Stackoverflow 
* 
* @property int $id The id of the object 
* @property string $name The name of the object 
* @property int $number The number of the object 
*/ 
class my_class { 
    public $id; 
    public $name; 
    public $number; 

    public function __construct() { 
     //Do something 
    } 

    /** 
    * Renames the object 
    * @param string $name Name to rename object 
    */ 
    public function Rename($name) { 
     $this->name = $name; 
    } 
} 

Questo è esattamente quello che preferiscono avere la documentazione, tuttavia completamento automatico Netbeans' non funziona correttamente, in quanto elenca ogni proprietà due volte. Ad esempio, se inizio a digitare $my_class_object->i il completamento automatico elencherà due proprietà $ id: una come descritto nel mio PHPDoc, e un'altra è descritta come una variabile sconosciuta con "PHPDoc Not Found".

C'è una soluzione che risolve il problema di Netbeans - aggiungi un blocco PHPDoc @var sopra ogni proprietà, tuttavia penso che inutilmente ingombra la mia classe, specialmente alcune delle mie classi che hanno 10+ proprietà.

C'è una [buona] soluzione per entrambi i miei problemi (documento pulito, corretto suggerimento Netbeans), o sto andando su questo in modo errato?

Answer 1

Il tag "proprietà" è specificamente ed esplicitamente oggetti "magici", ovvero quelle che in realtà non appaiono nel codice stesso. Questo è il motivo principale per cui il tag si verifica solo nella classe docblock. Pertanto, suppongo che gli IDE riconoscano il tag "proprietà" in questo modo dalla prospettiva "NON è visto nel codice". Certo, potrei capire l'aspettativa che il completamento automatico dovrebbe riconoscere l'esistenza di una tale proprietà, e quindi renderlo disponibile per te. Tuttavia, la mia scommessa è che gli IDE rimarranno con l'utilizzo solo del codice stesso per costruire un modello, e utilizzare solo informazioni docblock per integrare gli elementi che già vede nel codice.

L'utilizzo del tag "var" è l'unico modo corretto per documentare le proprietà "codificate". Se si vuole ridurre al minimo le linee necessarie al fine di utilizzare tale tag su tutte le proprietà, utilizzare un docblock di una riga:

/** @var int */ 
public $id; 

Inoltre, è possibile utilizzare il modello docblock di ridurre docblocks, dove tag somiglianza misura il tuo codice:

/** @var string */ 
public $name; 

/**#@+ @var int */ 
public $id; 
public $number; 
/**#@-*/ 

Questo non sembra un gran risparmio in questa breve lista, ma aiuta quando ci sono molte proprietà. Inoltre, funziona bene con i metodi.

Answer 2

Preferisco usare @var sopra ogni proprietà e nessuna @property. Sento che questo ti permette di associare più strettamente i commenti alla cosa che viene commentata. Ad esempio, i commenti per una proprietà sono sempre accanto alla proprietà. Se stai usando lo stile @property e hai una grande classe con una tonnellata di proprietà, è del tutto possibile che il commento che descrive una proprietà sia pagine lontane da esso.

Answer 3

Non sono sicuro della sintassi esatta ma sono sicuro che netbeans rispetterà la documentazione php standard.

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html http://www.phpdoc.org/