PHP: The phpdoc for enum getters/setters does not point to corresponding enum class

[bshaffer]

Feature Request for PHP:

in the phpdoc for getters and setters which correspond to an enum field, the generated class does not point to corresponding PHP enum class. The customer has no way of knowing where the enum values are held without going into the protos.

Example:

• FaceAnnotation::getJoyLikelihood()
• FaceAnnotation::setJoyLikelihood()

The return types and parameter types only show @return int and @param int respectively:

    /**
     * Joy likelihood.
     *
     * Generated from protobuf field <code>.google.cloud.vision.v1.Likelihood joy_likelihood = 9;</code>
     * @return int
     */
    public function getJoyLikelihood()
    {
        return $this->joy_likelihood;
    }

    /**
     * Joy likelihood.
     *
     * Generated from protobuf field <code>.google.cloud.vision.v1.Likelihood joy_likelihood = 9;</code>
     * @param int $var
     * @return $this
     */
    public function setJoyLikelihood($var)
    {
        GPBUtil::checkEnum($var, \Google\Cloud\Vision\V1\Likelihood::class);
        $this->joy_likelihood = $var;

        return $this;
    }

What we'd like to see instead

We can link the return and parameter types to the corresponding enum class:

    /**
     * Joy likelihood.
     *
     * Generated from protobuf field <code>.google.cloud.vision.v1.Likelihood joy_likelihood = 9;</code>
-    * @return int
+    * @return int one of the values in {@see \Google\Cloud\Vision\V1\Likelihood}.
     */
    public function getJoyLikelihood()
    {
        return $this->joy_likelihood;
    }

    /**
     * Joy likelihood.
     *
     * Generated from protobuf field <code>.google.cloud.vision.v1.Likelihood joy_likelihood = 9;</code>
-    * @param int $var
+    * @param int $var one of the values in {@see \Google\Cloud\Vision\V1\Likelihood}.
     * @return $this
     */
    public function setJoyLikelihood($var)
    {
        GPBUtil::checkEnum($var, \Google\Cloud\Vision\V1\Likelihood::class);
        $this->joy_likelihood = $var;

        return $this;
    }

This would also be implicitly fixed by implementing PHP native enums! See #15567

[bshaffer]

@piotrgradzinski to potentially work on this

[jguamie]

Assigning this to @bshaffer to assign when ready to work on.