Examples are the best documentation

Please don't follow this advice! The best thing about old school Python was that I could reliably pull up the documentation for a library and it would clearly list the arguments and return values for each function.

Now when I look at the documentation for many JavaScript, and even Python, libraries it's just examples. That's great if I'm trying to just throw something together as quickly as possible, but not if I need to fix a problem or actually learn the library.

Also having examples is fine, but they should be considered a bonus; not documentation.

Both are needed for good documentation. You start with the details and then finish with a few examples so that someone who has read the details can check their understanding. Sometimes the example is all you need, but most often there are far more possible combinations of options such that an example of all the useful ones would be several books long (there is no good way to sort/index them so someone wouldn't find the example they need if you wrote them all). So you start with an explanation of each option, and then a few examples that are as different as you can make them so readers get a sense of what is possible and can look back to the explanation to figure out the changes they need to get the example to do what they need.

Good documentation is hard, and very rare these days.