[pushpop]

Things may have changed since v7 but historically I’ve not found PHPs documentation any better than any other language.

In fact I remember a few occasions where I’ve ended up going by the advice of the comments rather than the documentation itself because the documentation was either out dated or just plain wrong.

[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?

[conradfr]

That has not been my experience but anyway there's a "Report a Bug" link on every doc page.

[pushpop]

That hasn’t always been there. Or of it has, then the maintainers haven’t ever done anything with bug reports because there have been errors in the docs for the entire life of 5.x.

I don’t really recall earlier versions of PHP being any better either. So I really don’t think PHP became popular because of the docs.

The other comments about how it was easy to learn and easy to deploy is far more accurate. If I recall correctly, back when PHP gained traction, your main options then were Perl (which understandably confused the hell out of a lot of people), ASP (VBScript / JSScipt and requires Windows NT + IIS so not a popular option) or JSP (Java and at that time was pain to deploy. So not something you’d expect a casual web developer to bother with). So PHP is like BASIC or Raspberry Pi of the 90s web. It was made for one specific job, it didn’t do it perfectly, but it was cheap, easy to learn and just about good enough to get the job done.

[snazz]

Maybe this is true, but by virtue of its popularity and ease of use, PHP has one of the largest selections of tutorials on everything, so that it’s possible to write code by just copy-pasting example snippets.

[pushpop]

Maybe within one very narrowly defined field. However move outside of your typical web services and tutorials take a sharp nosedive.

Really the kind of stuff that is well documented in PHP is the kind of stuff that is well documented in most general purpose languages. They are also the kind of problems that aren’t particularly hard to solve anyway.

But this is a moot point because the reason documentation was discussed was because it was credited as being one of the reasons for PHPs popularity. However tutorials wouldn’t exist if a language wasn’t already popular so your comment doesn’t reinforce the point made by the GP.