Well, rustdoc lets you include arbitrary Markdown files. So that case is not eschewed. With that said, they serve two different use cases. So as someone who ha

Well, rustdoc lets you include arbitrary Markdown files. So that case is not eschewed. With that said, they serve two different use cases. So as someone who has probably written more lines of docs than I have code in Rust, it doesn't make sense to me to ask for one and not the other. API docs with a bit of high level prose and some examples are very likely good enough for small focused libraries. For bigger libraries or projects, you are absolutely free to write prose that is disconnected from the API. You can do that in rustdoc or use some other tool (mdbook is very popular). But either way, you pretty much always want at least some API docs. > Doing it that way repeats the mistake of HTML. Annotation should be separate from content, not made into a sausage with it. This doesn't make any sense to me. The API of a library is both the signatures of items exported by the library and the documentation on those items. The docs might make certain guarantees about behavior, error/panic conditions and more. Those can't be described by the type system, and thus, the items and the docs are intricately connected. Both are required to define a library's API.