search

phpDocumentor / fig-standards

Standards either proposed or approved by the Framework Interop Group
http://www.php-fig.org/
Other
361 stars 85 forks source link

Naming consistency #140

Closed kwvanderlinde closed 5 years ago

kwvanderlinde commented 7 years ago

It seems to me that @return should really be @returns, for consistency with @throws and @uses. I also find it reads better to have all these tags be in the active voice (e.g., "this function returns a \DateTime") rather than being prescriptive (e.g., "this function must return a \DateTime")

zonuexe commented 7 years ago

PHPDoc is derived from Javadoc. I agree with your opinion, but I think that changing tag names is not a good idea.

ashnazg commented 5 years ago

Too massive a BC break, I'm afraid...

GaryJones commented 5 years ago

I think IDEs (like PhpStorm) are permissive of @returns - may even be a setting somewhere for which to use when doing /**[return] to pre-populate the DocBlock.

I'd rather the spec just allowed for a single choice, or at least made it clear that one was preferred.