Dokumentowanie parametrów Get/Post za pomocą Doxygen lub PHPDoc

Question

Przeglądałem dokumentację dla PHPDoc i nie mogłem znaleźć dobrego sposobu na udokumentowanie zmiennych Post przesłanych do różnych metod.

Tak więc zacząłem zaglądać do Doxygen z nadzieją, że dostarczy mi lepszego sposobu na udokumentowanie wszystkich tych zmiennych. Mój kod zawiera wiele żądań AJAX, więc większość zmiennych jest wysyłana pocztą.

Czy istnieje dobry sposób udokumentowania zmiennych post w doxygen? Mam problem z ustaleniem, czy otrzymam błąd po uruchomieniu ze standardowym znacznikiem parametru.

Jeśli nie, czy istnieje inny dokument, który może być pomocny w tym procesie? A może powinienem ręcznie udokumentować wszystko i zignorować szukanie automatycznego narzędzia do dokumentowania?

Dzięki!

Answer 1

Jeśli czytasz te metody bezpośrednio z $ _POST, a nie jako metoda argumentów, wtedy bym oprzeć na etykiecie, w sposobie w bloku dokumentacyjnym @uses:

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

Inną opcją może być 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'], "... :-)"; 
} 

Zdaję sobie sprawę, że „globalny” Hasło nie jest technicznie niezbędne dla superglobalną wewnątrz metody, ale to nie pomaga uzyskać to udokumentowane.

---

Edit

Należy zauważyć, że zgodnie z poradnik PHPDoc, w @uses ma pokazać relację dwukierunkową.

generatory dokumentacja powinna stworzyć @ używany po tagu w dokumentacji elementu odbiorczego, który łączy z powrotem do elementu związanego z tagiem @uses

Tak więc, chociaż semantycznie @uses może czytać lepiej , @see może również służyć do dokumentowania parametru $ _ [POST | GET | REQUEST]. Główna/jedyna różnica między nimi polega na tym, że @see ma być linkiem jednokierunkowym do FQSEN, do którego odwołuje się blok doc.