Yeah, PHP's docs are one of the truly phenomenal bits about the language. I've yet to see another language get this as right as PHP does.
PHP will continue to do well because it is the most extreme example of the "Worse is Better" (http://www.jwz.org/doc/worse-is-better.html) design style. "Worse is Better" software designs (e.g Unix, C) have shown to be far more popular in the market than more elaborately designed systems (Common Lisp, etc).
The comments are something I avoid about PHP docs. There are lots of bad PHP programmers who feel the need to help everyone else by posting their terrible implementation of X which people then just blindly copy... I like the idea, but in practice, I don't think it works very well.
Personally, one of the reasons I think PHP will continue to do well is the accessibility which is helped with the basic documentation. Can't remember how something works? php.net/foo. http://php.net/strpos - you get the 'official' docs, along with wiki-ish input from the community about gotchas, workarounds, extra tips, etc. Makes a big difference to many people compared to http://download.oracle.com/javase/7/docs/api/java/lang/Strin..., for example.