PHPDoc - Documenting @param's without the param in the function?

Question

I'm currently building up some phpdoc for a restful API - and I took to using the @param doc syntax for notating required params over POST.

However, after generating the phpdoc, I noticed that it refuses to list these parameters unless they match exactly with input variables into the method itself.

@uses and @see don't look good nor make much sense here when it comes to the phpdoc output. The style/look of the doc is perfect with the @param functionality.

Is there any way to override the rules put in place by PHPDoc, and allow it to generate @param blocks in the documentation, even if the param doesn't exist in the method itself?

Answer 1

Alright, I'm going to answer this with the solution I've found - I appreciate all the "do not do that" answers, but still hope that someone who finds themselves in a similar situation to myself ala "this needs to be done immediately without changing the format, and we cannot allot any time to this" will find it useful in the future.

You can maintain using the @param syntax if you initialise the method with the param specified, and simply set it to null - ensuring it doesn't break any existing calls.

/**
* Remove a group
*
* @param int $pricing_group_id Required
* @return mixed JSON array with remaining groups
*/
public function remove($pricing_group = null) {
    ....
}

Your PHPDoc output will now show the param type, name, and description as normal.

Keep in mind that this is not good practice - nor is it even remotely correct practice. But it'll work until you can convince a higher-up to allot you enough time to rebuild the existing documentation on a more suitable platform.

Answer 2

If you want to document your API, I suggest you use proper tools like API Blueprint or Open API Spec.

And by using Swagger, you can even use annotations (which is what you apparently want) to document the API and in turn, generate the documentation out of it.

Just don't use PHPdoc for it, because that's just mixing concepts altogether.