Documentazione Get/Post Parameters con Doxygen o PHPDoc

Question

Guardavo attraverso la documentazione per PHPDoc e non riuscivo a trovare un buon modo per documentare le variabili Post che inviavo a vari metodi.

Così, ho iniziato a esaminare Doxygen con la speranza che mi avrebbe fornito un modo migliore per documentare tutte queste variabili. Il mio codice richiede molte richieste AJAX, quindi la maggior parte delle variabili viene inviata per posta.

Esiste un buon modo per documentare le variabili di post in doxygen? Sto riscontrando problemi nel determinare se visualizzerò un errore nell'esecuzione con il tag del parametro standard.

In caso contrario, c'è un altro documentor che potrebbe essere utile in questo processo? O dovrei semplicemente documentare manualmente everythign e ignorare la ricerca di uno strumento di documentazione automatica?

Grazie!

Answer 1

Se i metodi stanno leggendo quelli direttamente da $ _POST, piuttosto che come argomenti del metodo, poi avrei appoggio al tag @uses nel docblock del metodo:

/** 
* My foo() method 
* @return void 
* @uses $_POST['bar'] directly 
*/ 
public function foo() 
{ 
    echo "I use ", $_POST['bar'], "... :-)"; 
} 

Un'altra opzione potrebbe essere il tag @global :

/** 
* My bar() method 
* @return void 
* @global mixed uses the 'bar' key from the $_POST superglobal directly 
*/ 
public function foo() 
{ 
    global $_POST; 
    echo "I use ", $_POST['bar'], "... :-)"; 
} 

mi rendo conto che la parola "globale" non è tecnicamente necessario per una superglobale all'interno di un metodo, ma aiuta farlo documentato.

---

Modifica

nota che in base alla guida di riferimento di PHPDoc, @uses è destinato a mostrare una relazione a due vie.

generatori di documentazione dovrebbe creare un @ utilizzato-per tag nella documentazione dell'elemento ricevente che collega torna all'elemento associato al tag @uses

Quindi, anche se semanticamente @uses potrebbe leggere meglio , @see potrebbe anche essere utilizzato per documentare un parametro $ _ [POST | GET | REQUEST]. La principale/unica differenza tra i due è che @see è pensato per essere un collegamento unidirezionale al FQSEN a cui si fa riferimento nel blocco doc