While you are generally correct that complex software is complex, and thus invariably contains bugs, in this case the behaviours of read() and value() are well-defined and consistent with the observed behaviour – it's all there in the docs.

Understanding them is often difficult, and examples are sparse, but it's by no means an impenetrable black hole of knowledge. Please don't spread ignorant FUD and don't assume the worst by default, sometimes there actually is a good explanation.