[ianstormtaylor]

+1 I'd much rather side with the "document every function" camp and have a few extra comments, than inevitably degrade to the "document close to nothing" camp and have functions named "normalize" and "resolve" that have to be in their entirety to understand what they do. That being said, I like to drop the `@return void` and `@api public` type entries because they're almost always self-evident, or even not true, like in Javascript where everything is public if exposed and people will reach in no matter what you do.

Writing docblocks can also be a nice way to check yourself from writing bad code. If you find yourself adding 4 different `@param` entries it makes you stop and think, "why is my function taking 4 arguments, it's probably poorly designed".