No seriously, that is actually one of the best things. The comments on PHP docs are far more informative than the actual documentation for many other languages. Most everywhere else the caveats are simply left up to the developer to discover the hard way.
The best thing are the comments in the docs of people telling you how wrong the docs are.