I think in most cases, back when I worked there, I would have instead searched the monorepo for targets that depended on this library (an easy lookup), and look at how they used it.

Some code libraries had excellent docs (recordio, sstable, mapreduce). But yes, reading the header file was often the best place to start.

I’m not at google so I’ve got no idea.

Reading the code, especially the header files, seems to be pretty standard as far as what I see in non-open source code. So, it’s been my typical dev experience, I’d say if you’re somewhere that has gleaming, easy to understand docs that are actually up to date with the code you all have too much time on your hands, but I serially work at startups that are running to market.

Header file gives you a view into some narrow window of the system, API, pipeline, and you probably have no idea which header files are important and which are part of some internal implementation.

10 mins spent on readme with some high level details is investment with 100x return for lib users.

These header files have “doc”like comments in them.

that's cool, not sure how it addresses points I described though.