PHP's docs are good and bad in the same way that PHP itself is good and bad. For PHP the language reference is quick, easy, simple. Offers the syntax with required and optional parameters followed by a quick and typical use case. When that isn't sufficient, the comments may or may not have the exact use case you're looking for, many times they do. So it's all very convenient for drive-by-programming, like PHP. Good at quick'n'dirty, not so great for more involved, or for more carefully thought out solutions.