It is order of magnitudes easier to understand behavior through examples than through a reference-like documentation. People suck at naming things, and then documenting them. Just today I spent the last few hours trying to figure out how to get something to work because a parameter only worked if another paramter had a specific value. There was too much magic to try and figure out the code, llms wrongfully told me the latest version doesnt support the parameter because it couldn't find any documentation.
Ultimately, creating a small example that I know should've worked and changing things in a way that I could narrow down the problem worked best.
The point to all this is that examples often encapsulate multiple things into a condensed format, that is extremely high fidelity (since it's typically a code example that runs and has output). Things like Api documentation in comparison typically cover a huge surface area, and have way less effort in maintaining them.
Also for the record, I absolutely don't trust libraries on behavior that isn't extremely obvious, explicit and so absolute that it's almost effortless to find out (I am talking first thing on README, entire sections showing that one thing, or definition through types). I just assume that things like behavior around status codes are going to change, and do my best in the calling code to mitigate issues as much as possible.