Thanks for the reviews, suggestions, discussion! The PR is moving along to merge, and there is a slightly updated version of the docs now online.
All: the Lwt reference docs currently include a “compressed” version of an Lwt tutorial, and some other things that should be on separate pages. This is because those other pages haven’t been written yet, but I felt I needed to have skeletons of those explanations around to write a good
lwt.mli. So, those explanations are parked in
lwt.mli, but will be factored out and expanded later.
The “logical” order to write the docs is to start with examples, tutorials, and conceptual pages. However, thinking about having to do
lwt.mli was giving me by far the most stress, so I decided, for personal reasons, to do it first That’s why things that don’t belong on that page ended up there. I’ll probably do
lwt_unix.mli and a few other intimidating APIs next, before turning to non-API manual pages.
I agree about tables of contents, function lists,
<details> etc. I’ll think a lot about the presentation and experiment with it. Also, @yawaramin, glad to see the ocamldoc TOC PR you’ve sent
I’ve started helping out with
odoc recently, so maybe we will be able to solve presentation issues nicely there.
@DerRechner, I got rid of the question, and also rephrased the sentence introducing the
>>= operator. Thanks for pointing those out.