[chiefalchemist]

Perhaps not better, but there certainly have been worse.

As for the comments. Yes. But at least they're there, and quite often helpful. Plenty of times I've read other docs where I wished they had commenting but alas didn't.

[ptx]

The comments are only needed because the documentation is often wrong or confused. And, of course, usually most of the comments are wrong too.

Other languages don't need comments because they at least aim to have documentation that's correct.

[chx]

If you find the documentation wrong or confused please let us know. https://bugs.php.net/ We do our best. I was granted access some ten years ago and whenever I find a confusing page I fix it. I know there has been terrible pieces before but for the last oh five or six years I don't really find anything too bad. Please let us know what you found wrong. Thanks!

[ptx]

I was mostly responding to the idea in an ancestor comment that PHP has unusually good documentation (better than that of other languages), "best of all" having comments.

I'm sure the PHP documentation is getting better all the time! Other languages also have good documentation, though. And as pushpop said in an earlier comment, the reason that the comments were useful historically is that the documentation was not always correct or complete. (Perhaps in part because the the language used to have a lot more unintended quirks?)

[welly]

"Often wrong"? Really? By often, 50% more wrong than right or less? Or more? I can count on one hand the number of occasions I've found the documentation to be incorrect.

[pushpop]

"Often" is a fuzzy term and it's used subjectively here. It doesn't mean "most of the documentation" (which would be the >50% goal post you're driving at). It simply means "a lot of the time $OP checks the docs". It might be the case that the only time they need to check the docs is for some of the more advanced features of PHP where errors are more likely to be found in the docs. While you could correctly argue "selection bias", it doesn't still take away from the OPs perspective that it often happens to him.

[chiefalchemist]

I don't see it that way. The comments are there to prevent others from re-inventing the wheel, to share insights, etc. Yes, sometimes that also highlights a "bug" or some other "flaw" but that's the rare exception.

Maybe it would help if you listed some links to language docs that you feel the rest should use as benchmarks?