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?

Bart van Ingen Schenau · Accepted Answer · 2013-12-10 11:11:48Z

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.

answered Dec 10, 2013 at 11:11

Bart van Ingen Schenau

15.9k4 gold badges34 silver badges42 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

Programster Over a year ago

Thank you, you make some good points. The only reason I specified the variable in the return was this was the policy at a previous company for the next programmer who wished to edit the method. I guess this was just bad practice.

Bart van Ingen Schenau Over a year ago

@Stu2000: You might say so. The only case where I see any value in explicitly documenting which variable holds the return value is if the method is too long or too complex.

Collectives™ on Stack Overflow

Netbeans phpdoc @return

1 Answer 1

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related