Examples are best only for the beginner/occasional users. For more experience devs, you want regular docs, with full parameter list.
Case in point: requests. Google always drops me to the pages like Quickstart[0], which are full of examples. But they are useless for advanced users! Yes, even my limited brain can remember that you call "get" to issue HTTP GET. What other options does it take? Does it take a timeout? How do I pass in content-type? Does raise_for_status ignore 204?
Both have their merits, but if developer only has time for one, I'd go for proper doc.
[0] https://requests.readthedocs.io/en/latest/user/quickstart/
replies(8):