Zapytanie params i PHPDoc

Question

Powiel możliwe:
Is there a standard for documenting GET/POST parameters?

Próbuje dowiedzieć się, że najlepszym sposobem dokumentowania parametrów żądania poprzez PHPDoc w sposób, który ma sens. W szczególności mam pewne akcje kontrolera Zend Framework, które otrzymują parametry za pośrednictwem GET/POST, ale nie są funkcjonalnymi paramami. Czy to ma sens?

/** 
* Display a pagination/grid list of rows. 
* 
* @param string $_GET['order'] What field to sort on 
* @param string $_GET['dir'] Direction to sort; either ASC|DESC 
* 
* @return void 
*/ 
public function listAction() 
{ 
    $order = $this->_request->order; 
    ... 

Gdybym generowane dokumenty dla tej metody, nie byłoby wskazanie, że „porządek” oraz „dir” mogą być przekazywane za pośrednictwem łańcucha URL do tej metody. Czy byłoby lepiej, gdybyśmy zamiast tego używali tylko @var zamiast

@param string $order 

?

Myśli mile widziane.

Answer 1

bym unikaj muckowania z @param.

Można również utworzyć metodę _validate(), aby było to oczywiste w kodzie. Następnie można użyć _validate(), aby utworzyć test szwu do testowania jednostkowego.

/** 
* Display a pagination/grid list of rows. 
* 
* Requires $_REQUEST['order'] and $_REQUEST['dir'] 
* 
* @return void 
*/ 
public function listAction() 
{ 
    list($order, $dir) = $this->_validate($this->_request); 
    ... 

private function _validate($request) { 
    if (!$request->order) 
     throw new InvalidArgumentException('"Order" must be in request'); 

    if (!$request->dir) 
     throw new InvalidArgumentException('"Dir" must be in request'); 

    // maybe clean vars??? 
    //Zend_Filter_Numeric..... 

    return array($request->order, $request->dir); 
} 

Answer 2

Generalnie albo używam tego, co zaproponowałeś, albo umieść prosty komentarz bez phpdoc, gdy kod jest zbyt długi lub po prostu nie rób nic.

Pomiędzy tymi trzema, twoje rozwiązanie jest najlepsze, jak sądzę.

Tylko jedna rzecz, którą powinieneś sprawdzić: czy ładnie to działa, gdy generujesz phpdoc?

W teorii, jak PHPDoc używa nazw oddawać w doc-bloku, przypuszczam, że powinniśmy ...

Jeśli tak ... dobrze, nie widzę lepszego sposobu; nie potrzeba lepszego sposobu: nie sądzę, aby można było zrobić coś czystszego/czytelnego/zrozumiałego.

mi się nie podoba

@param string $order 

pomysł: nic pokazać $order powinny być podane w $_GET i nie jest „prawdziwym parametr metoda”; więc wolałbym uniknąć tej składni.

Nigdy @ var użytkownika parametrów, btw: tylko dla zmiennych, kiedy czuję potrzebę dokumentowania ich (co nie jest często, przynajmniej dla krótkich metod/części kodu)