[mapgrep]

In open source the trend unfortunately seems to be toward a Readme.md with a couple of simplistic examples, then you’re left to read the source in lieu of a proper API reference.

I still remember CPAN perldocs as a high water mark for docs. They had specific sections for examples, starting with the summary at the top, and another for proper reference. And more importantly a strong culture of good docs. The examples tended to be close to comprehensive, progressing from simple to complicated problems. Then there would be a rundown of arguments and return values for the key methods.