After experiencing the wall of well-intentioned garbage that is php.net I no longer like comments in docs. Those examples and clarifications of edge cases should be in the documentation itself.
And how do you discover these edge cases if you don't have comments? The point of the comments is to point out common issues, use cases and potentially, common misunderstandings.
