Search code examples
phpphpdoc

PHPDoc for parameters and return type

I'm using eclipse to build my php applications and the Source > Generate Element Comment function for automatically creating doc blocks.
I'm wondering a bit about the format because the return type is set as full-qualified class name but the parameters not.
Is this a bug of the IDE or is it the common convention?

Here's an example:

/**
 * Executes the given service.
 *
 * @param string $serviceClass
 * @param ParametersInterface $inputParams
 *
 * @return \ZF\Hal\Entity
 */

And I have the following uses:

namespace MyApp;

use ZF\Hal\Entity;
use Zend\Stdlib\ParametersInterface;
Solution

  • It's most likely just a behavior oddity in Eclipse, where the auto-recognition code for parameters is possibly not the same code that auto-recognizes returns. I would bet the parameter recognition is more naive, in that it probably keys specifically off your method signature. So, if your method signature is

    public function executeService(string $serviceClass, ParametersInterface $inputParams)

    then the auto-doc probably gets exactly just the ParametersInterface you have in the code.

    However, if you wrote the code this way

    public function executeService(string $serviceClass, Zend\Stdlib\ParametersInterface $inputParams)

    then I'd bet the auto-doc would show the fully namespaced name.

    It wouldn't hurt to report it to Eclipse (if it's not already been reported).