referenced parameters not recognized

[flack]

I have a docblock looking like this:

/**
 * Summary
 *
 * @param array &$args Parameter description
 */
public function test(array &$args)

This produces an error in the log to the effect that no documentation for $args was found. Also, in the rendered documentation (at least in clean and responsive themes) the & sign is not rendered in the signature, so that by reading the API doc you have no idea that this is a reference.

[mvriel]

Hi @flack,

You don't need to pass the ampersand (&) to the DocBlock's @param tag; phpDocumentor reads that from the signature. The Clean theme should show that it is a reference, we will have to take a look why that is not showing.

[flack]

Hi @mvriel

I just tried removing the ampersand from one of the affected docblocks, and now, the error disappeared and the ampersand is rendered correctly in the documentation (I've tried with responsive-twig). So it seems that having the ampersand present in the docblock caused the original problem.

The codebase I'm working on is quite old, and these docblocks are still from the time when the documentation was generated by phpdocumentor1, which had the opposite behavior (i.e. if you didn't have the ampersand in the docblock, then you would get an error). Would you consider adding support for the ampersand in the @param tag to provide backwards compatibility?

If not, I guess I can just do one giant global seach and replace, but at least to my taste, it seems cleaner to write @param &$args

[mvriel]

I think it would not hurt to add backwards compatibility to this item

[flack]

Thanks! I'm looking forward to it. Let me know if there's anything I can do to help!

[samlev]

I agree with @flack - documentation should be explicit, and should allow @param array &$var (or similar).

[jaapio]

Fixed in v3 release: