php - Is there a standard for documenting GET/POST parameters?

Question

In a PHP project, even when front controller logic is used for the main application, there can be many stand-alone scripts, ajax snippets and so on.

Is there a standardized way - either PHPDoc or something else - to define in the first comment block of the script what GET and/or POST parameters the script will accept / require and of which type they are?

I usually help myself by just adding @params as if the file were a function, and a @return explanation for what the script does and returns, but maybe there is a more specialized way I do not know of.

Answer 1

Pekka,

I'd look into using a WADL to document interacting with your API. Its not directly answering your question - because this isn't generated from source code documentation, its XML, and maintained separately.

It does answer this directly:

what GET and/or POST parameters the script will accept / require and of which type they are

You can place sample payloads in the document, along with URI params, accepted content-types, error codes/responses/payloads. I find it very valuable, and with a WADL, someone can code a client against your API.

For more info: http://research.sun.com/techrep/2006/abstract-153.html and: http://en.wikipedia.org/wiki/Web_Application_Description_Language