Good to hear the feedback (though in my own documentation-related request: fewer words! I think that could have been conveyed more clearly in 1/4 the space.)
Seems to me like the core of the issues you raise are the things we know, and that are related to the mismatch between the techniques used for constructing Base (and our libraries more generally) and the current state of the doc-generation tools. A sad but true fact is that the mli’s in our libraries are generally easier to read than the generated docs:
(Which is not to say that the docs themselves couldn’t use some more detail. They surely could. But it’s the double-underscores and extra indirections that are really deadly.)
It’s perhaps no surprise that within Jane Street, we read the mli’s far more often than we look at the generated docs. (And we have nice shortcuts in our tools for bringing those mli’s up.)
These are all things that we want to see fixed, and I’m hopeful that the work coming out of OCaml Labs on that front will solve the tooling issues, at which point we can do more to integrate the generated docs into our workflows, and improve the docs yet more.