PHPDoc: @return void necessario?

È davvero necessario fare qualcosa del genere:

/** * ... * * @return void */ 

Ho parecchi methods che non hanno un valore di return, e sembra davvero superfluo inserire qualcosa di simile nel commento. Sarebbe considerata una ctriggers forma lasciarla fuori?

Se chiarisce la documentazione, lasciala, ma non è strettamente necessaria. È una decisione interamente soggettiva.

Personalmente, lo lascerei fuori.

MODIFICARE
Sono corretto. Dopo un po 'su google, la pagina di Wikipedia dice:

@return [tipo descrizione] Questo tag non deve essere utilizzato per costruttori o methods definiti con un tipo di reso vuoto.

Il sito Web phpdoc.org dice:

@return descrizione dei dati
@return datatype1 | descrizione datatype2

Il tag @return viene utilizzato per documentare il valore restituito di funzioni o methods. @returns è un alias per @return per supportre i formati di tag di altri documentatori automatici

Il tipo di dati dovrebbe essere un tipo PHP valido (int, string, bool, ecc.), Un nome di class per il tipo di object restituito o semplicemente "misto". Se si desidera mostrare in modo esplicito più possibili tipi di return, elencarli separati da spazi (es. "@return int | string"). Se un nome di class viene utilizzato come tipo di dati nel tag @return, phpDocumentor creerà automaticamente un collegamento alla documentazione di quella class. Inoltre, se una function restituisce più valori possibili, separali utilizzando il simbolo | carattere e phpDocumentor analizzerà tutti i nomi di class nel valore restituito. phpDocumentor mostrerà la descrizione opzionale non modificata.

Sooo … Sulla base di ciò, direi di lasciare fuori il vuoto. Non è standard, alless.

Secondo phpDocumentor, @return void è valido:

http://www.phpdoc.org/docs/latest/guides/types.html#keywords

… questo tipo è comunemente usato solo quando si definisce il tipo di return di un metodo o function. La definizione di base è che l'elemento indicato con questo tipo non contiene un valore e l'utente non deve fare affidamento su alcun valore recuperato.

Per esempio:

  /** * @return void */ function outputHello() { echo 'Hello world'; } 

Nell'esempio sopra non viene specificata un'istruzione return e quindi il valore restituito non è determinato.

Fonte: http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html ( pagina archiviata ).

Devo modificare la mia risposta a causa di qualcosa che ho imparato di recente.

L'utilizzo di @return void invece di @return null ha un significato molto speciale, si considerino i seguenti due esempi di codice PHP.

 <?php /** * @return void */ function return_never() { echo "foo"; } /** * @return null|string */ function return_sometimes() { if ($this->condition()) { return "foo"; } } 

Nel primo esempio, PHP restituirà NULL , poiché PHP restituisce sempre NULL . Ma il valore restituito è inutile per il chiamante in quanto non dice nulla su ciò che la function ha fatto. Gli IDE possono utilizzare le informazioni documentate di @return void per indicare allo sviluppatore che viene utilizzato un valore di return che non ha alcuno scopo.

 <?php $foo1 = return_never(); $foo2 = return_sometimes(); 

La prima chiamata è insensata poiché la variabile conterrà sempre NULL , la seconda potrebbe effettivamente contenere qualcosa. Questo sta diventando ancora più interessante se mettiamo le chiamate di function in un condizionale.

 <?php if (($foo1 = return_never())) { // Dead code var_dump($foo1); } if (($foo2 = return_sometimes())) { var_dump($foo2); } 

Come puoi vedere, @return void ha i suoi casi d'uso e dovrebbe essere usato se applicabile.

Si noti inoltre che farà parte del prossimo standard PHP PSR-5. [1]

[1] http://www.php-fig.org/psr/

Ecco come capisco e utilizzo le annotazioni PhpDocumentor:

 <?php /** * This method always returns string. * @return string */ public function useCase1() { return 'foo'; } /** * This method returns 2 data types so list them both using pipeline separator. * @return string|false */ public function useCase2() { if ($this->foo === 1) { return 'foo'; } return false; } /** * This method performs some operation and does not return anything so no return * annotation is needed. */ public function useCase3() { $this->doOperation(); $this->doAnotherOperation(); } /** * If condition passes method returns void. If condition does not pass it returns * nothing so I think that specifying the return annotation with void is in space. :) * @return void */ public function useCase4() { if ($this->foo === 1) { $this->doOperation(); return; } $this->doAnotherOperation(); } 

A partire da php 7.1, void è un tipo restituito valido e può essere applicato a una function.

Lo aggiungerei sempre sul docblock.

Un altro vantaggio di scriverlo è quello di differenziare i methods void dai methods che possono restituire qualsiasi cosa, ma non hanno una voce @return sul docblock per negligenza.