PHPDoc - Documenting #param's without the param in the function? - php

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

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.

Answer 2

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 3

You can do this by utilizing "optional". IE:
#param string $variable (optional) Blah.
See other examples at https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html .
This is to be used in the use case of when a parameter is optional, unlimited parameters, etc.

Answer 4

You might consider using a "custom" tag, maybe #parameter, so that it is listed "as is". You won't get the same hyperlink behavior for class names as the param tag provides, but you won't be limited by the lack of parameters in the code signature itself. Maybe use an inline link tag in the parameter description that points to the class type of the parameter. Otherwise, the uses, see, or link regular tags can be on separate lines as convenient links to the classes that are your parameter types.
There is currently no way to disable the internal behavior of "actual code signature overrides param tags" logic.

Answer 5

I believe you can use the same approach for documenting virtual methods as a workaround, i.e. via a #method entry in the phpDoc header for the class.
E.g.:
/**
* ...
*
* #method mixed remove(integer $pricing_group_id) Remove a group and return a JSON array with remaining groups.
*/
class YourClass {
...
// see class header for phpdoc entry
public function remove($pricing_group = null) {
....
}
}
A downside is that (to my knowledge) this approach does not provide a means to enter explicit description entries for the method's parameters and return value.