Comment by raggi

show me a christian that grok'd the entire bible before calling themselves a christian, and i'll show you a developer who reads the entire behavioral specification of a library before using it.

your idea works for libraries that are small, it's appalling for libraries of any significant size.

the point of a readme is to provide a useful summary that is quick to start using for the critical path use cases.

if you look at a web framework in a language you don't know as an example, and try to find the introductory use cases in the tests, this should give you some idea of what you're suggesting.