Commento PHPDoc, Class vs File

Question

Commento PHPDoc, Class vs File

#1 da (6 voti)

4

Sto cercando di standardizzare il mio codice il più possibile, compresi DocComments, usando PHPCS .

Sembra che gli standard PEAR contengano due filtri che richiedono quasi esattamente gli stessi tag visualizzati nella classe e nei file DocBlocks:

PEAR.Commenting.ClassComment
PEAR.Commenting.FileComment

Entrambi vogliono vedere questi tag: @category , @package , @author , @license , @link .

----------------------------------------------------------------------
FOUND 10 ERRORS AFFECTING 2 LINES
----------------------------------------------------------------------
  6 | ERROR | Missing @category tag in file comment
  6 | ERROR | Missing @package tag in file comment
  6 | ERROR | Missing @author tag in file comment
  6 | ERROR | Missing @license tag in file comment
  6 | ERROR | Missing @link tag in file comment
 13 | ERROR | Missing @category tag in class comment
 13 | ERROR | Missing @package tag in class comment
 13 | ERROR | Missing @author tag in class comment
 13 | ERROR | Missing @license tag in class comment
 13 | ERROR | Missing @link tag in class comment
----------------------------------------------------------------------

Sarebbe sciocco ripeterle perché tutti i miei file sorgente contengono solo una singola classe (o interfaccia o tratto).

La mia domanda è, quali tag dovrebbero andare dove. Dovrebbero tutti andare nel commento del file, tutto nel commento della classe, o dovrebbero essere divisi tra i due.

php documentation

posta DanielM 07.10.2015 - 15:09

fonte

1 risposta

Leggi altre domande sui tag php documentation

Se un Closeable lancia un'eccezione se usato dopo essere stato chiuso, anche se non è necessario? Come calcolare i valori min / max dei numeri in virgola mobile?

score 6 · Accepted Answer

Basandomi su ciò che riesco a trovare, questa è la mia opinione che pongo come risposta. Mi piacerebbe davvero un feedback su questo. Questa risposta è basata su uno standard proposto (non accettato)

Breakdown:

Esaminare lo standard PSR-5 proposto , in particolare la descrizione di ogni tag ha aiutato un po '.

@category

Deprecato a favore di @package che essenzialmente fa la stessa cosa, quindi può essere rimosso dallo sniff.

@package

Può essere utilizzato in entrambi, tuttavia nel blocco di file a cui si applica: funzioni globali, costanti globali, variabili globali, richiede e include. Nella classe si applica alla classe e a tutti gli elementi contenenti. Supponendo che il tuo file contenga solo una classe, il tag @package sarebbe privo di significato nel blocco di file.

@author

Questo può valere per qualsiasi elemento strutturale. La documentazione non aiuta in modo specifico a rispondere alla domanda su quale, comunque dal momento che il file contiene la classe, direi che dovrebbe apparire nell'elemento più comprensivo (il commento del file), con altri autori che aggiungono un tag @author a qualsiasi sottoelemento scrivono.

@license

Anche in questo caso, questo può essere applicato a qualsiasi elemento strutturale, ma viene applicato a tutti gli elementi secondari, pertanto il file sembra più appropriato.

@link

Anche il collegamento è deprecato a favore di @eeee

@see

@eeee è più loose di @link e potrebbe essere felicemente applicato sia al file che alla classe. Ad esempio il file potrebbe fare riferimento al sito web del progetto, il file potrebbe fare riferimento alla documentazione per la classe.

Sommario:

Quindi questo è quello che penso che il file dovrebbe essere approssimativamente come

<?php
/**
 * FileName.php
 * @author    My Name <[email protected]>
 * @copyright 2015 My Company
 * @license   Licence Name
 * @see       Link to project website
 */

namespace My/Namespace;

use Another/Namespace/Class;

/**
 * Class summary
 * A longer class description
 * @package Vendor/Project
 * @see     Link to class documentation
 */
class MyClass {
    ...
}