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

Answer 2

phpDocumentor won't like @param and @return tags in the file-level docblock...

If you choose a separate file to document them in, as per Mr-sk's answer, you can use @link to point there, but it won't be immediately visible in your file's documentation page... it'll just be a hyperlink that you'll have to click to go see the info. If you want any of that file's contents to be visible on the documentation page for your script file, you could use the inline {@example} tag to point to it, or even just certain lines in it, e.g. {@example /path/to/file 3 5} to show only lines three through five.

In this scenario, I'd probably choose to just explain things in the long description of the file-level docblock, since there's not actually a direct way of tagging your parameters to where phpDocumentor will recognize them as code elements anyway. If any of the parameters I used in my descriptions were indeed documented code elements that originate somewhere else in the code, I'd use the inline {@link} tag to point to that code element.

For example, let's say there are some constants defined in another code file, and those elements' own documentation gets generated when that other file is parsed. If my long description that I write in the file-level docblock of a script-only file (like yours) talks about those constants as parameters, then my sentence might be:

If $POST['foo'] is set, its value should always be either {@link BAR_CONST} or {@link BAZ_CONST}.

References:

• inline {@example} -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineexample.pkg.html
• inline @{link} -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlinelink.pkg.html