I can agree that PHP is documented. That it is well documented however is something I'm very much willing to argue against.
PHP has string-operations documented to be "binary-safe" without ever saying what that is supposed to mean, if it's good (it's not), if it's bad (yes, yes, yes it is) and why you should have an opinion on that at all. Nothing about that. "Binary-safe" is not defined anywhere. It just "notes" that all these operations which should operate on text is "binary-safe". And "safe" makes it sound like a good feature, right?
Documentation like this is probably written by people who have no idea what a character encoding is and thinks that being able to strpos() on raw byte-data is a "cool feature", without understanding that text and it's encoded representation are two very different things.
Basically, the documentation is written by people lacking any deep understanding of the subject they are covering, and they pass their confusion on to whoever may be unfortunate enough to stumble upon it.
So... Is bad documentation better than no documentation? I don't know. Maybe? Still: PHP documentation, good or bad, represents the blind leading the blind.
If you want "extremely well documented", head over to MSDN and check the .net docs. It's systematic, it's consistent and it's thorough. It's written by people who understand the difference between Unicode, UTF8, text and bytes. Or whatever else the subject you are reading about covers.
But people peddling in PHP wouldn't know that, because they wouldn't want to go too far outside their comfort-zones, and hey, they definitely wouldn't want to look at anything done by Microsoft.
The very small percentage of php developers who have ever had to deal with binary data probably had their hands burnt enough to figure out what binary safe was. While I'm not arguing that documentation should have vague references, its not that hard of a tradeoff between just mentioning something that should be explained over pages, as opposed to not having it there at all.
Plus, the comments section makes it very useful to have examples and clarifications. Its not as bad as you make it out to be.
I'm used to dealing with perl 5, which has quirks of it's own, but at least their documented (a little too much sometimes). I learn a lot about many things by reading the perl docs.
Here's "Gory details of parsing quoted constructs" (no that I have read it..)
http://perldoc.perl.org/perlop.html#Gory-details-of-parsing-...
But, sticking with it, it's comes down to there being a huge market in parts and service. Something like all taxis in the US still being Ford Ts, with very little forecast of change.
I agree with the first part. But when the rest of the world has moved on to '56 Chevy Bel-Airs, does anyone really want a "revived and improved" Model T?
-Take away PHP and the internet would break. The vast majority of websites are either written in PHP or have a PHP back end.
-The LAMP/LNMP stack is by far one of the most deployed web server configuration.
-PHP is extremely well documented and it's been around so long that it's easy to find solutions on the web.
PHP is the Model T of web languages: people love to laugh at it because it's old and ugly but it nearly single-handedly revolutionized the landscape. I for one applaud any efforts to revive and improve this language.