Netbeans phpdoc @return

Question

I have been documenting my methods in Netbeans like so:

/**
 * Fetches a list of all the task ids that are dependent on the specified task being finished
 * before they can be marked as available to work on.
 * @param int $taskId - the id of the task we wish to fetch the dependency list for
 * @return Array<int> $dependents - array list of tasks dependent on the specified task 
 *                                      being completed.
 */
 public function getDependencyList($taskId)

Now if I rename the variable $taskId within the method (with cntrl-r), then the documentation is automatically updated. Unfortunately, this is not the case with the @return property. Is there a way to enable this or am I simply generating my documentation incorrectly?

Answer 1

You are writing your documentation incorrectly. Just think, what value does it have to me, as consumer of your documentation, to know that inside your function the return value is first captured in a variable called $dependents?

It has none. I don't care how the function is coded, I only care about that it returns me a list of dependencies, as the function's name indicates, and how I can access elements of that list (by accessing it as an array of integers, as the type specification states in the documentation).

For parameters, the case is different, because there the parameter name can be used to determine at which position in the argument list the parameter is expected, but that consideration does not exist for return values.