Meanwhile, I find the PHP docs far more readable/accessible than almost any other language. Compared with the official Python or (shudder) Java docs, and they're far superior, IMO.

If it makes you feel any better, at least the comments are next to the documentation? Really big projects that people rely on every day -- things like Rust's Cargo or Google's Flutter -- are riddled with bugs and limitations, requiring frustrating boilerplate workarounds to make basic things work correctly, and they generally only have mention of the problems in the comments on the billion 5-10 year old open issues in their task tracker.

Clojure crowdsources "examples" (to good effect, IMO). For example: https://clojuredocs.org/clojure.core/assoc-in

The php docs are themselves a public GitHub repo, so it's a bit sad if insightful comments don't affect change in the docs