See the new docs here 
This is only one module. There are many others left to document, in addition to examples and a tutorial to write. See the docs project for an overview of the whole undertaking.
All feedback is welcome Please comment here, or review in the GitHub pull request:
I think you are providing too much details in the doc strings of values which makes the API reference unreadable. This makes it difficult to navigate the API and see what it actually offers, which once you get familiar with the API becomes your main interaction pattern and the one you should optimize for.
In my opinion itās better to discuss things more extensively in dedicated sections (e.g. at the end of the module) and link to that from the doc strings. A loosely related example of this is Fpath which provides a lot of examples for most of the functions since path manipulation with relative segments is such a tricky thing. Having them directly in the doc strings would make the API reference unreadable and difficult to navigate.
I agree with this. I found the API docs more and more overwhelming as more were written, exactly because I couldnāt really see at a glance the various type signatures and summaries anymore. But I also wanted to make sure to get the minimum level of detail that I think is required. Iām still thinking about how to best organize this much information in an OCaml context, and any further suggestions are welcome.
The way Elixir docs handle this is to put a Summary (an example module, Ecto.Repo) after the overview in the generated docs, which only enumerates defined types and functions of a module. Elixir folks really like comprehensive expositions on their docs, and IMO it really adds to the perception that the language is beginner friendly. Although I realize this does not solve the navigation problem when you read the mlis directly. But perhaps itās better to direct people to some online docs with navigation rather than the mlis themselves? Just throwing out ideas.
And also, although I know itās written that the appearance and postprocessor here is temporary, another feature that I would like to be present in such postprocessed docs is the ability to jump to the definition (Elixir docs has it denoted by </> on the top-right of the page and on every type/function section). But Iām not sure if the tools available (and the separation of mli and ml files) support thisā¦
odoc supports this, see docs.mirage.io or treat your opam switch with odig. I think it would be better for @antron to make the work on the lwt docs fit in the odoc/odig setting rather than have its own pre-processor, otherwise the work on the doc will not be available to local users of the package.
Sorry I think I used the wrong term, I meant jumping to implementation (as in the content of the ml file in the repository). I might be mistaken but I think odoc only supports jumping to the definition in other docs (whether the same page or different)?
Ah yes sorry, I thought you meant simply linking to definitions on the pages. No, full code browsing is not supported by odoc.
For what itās worth, I find the Fpath-style reference docs hard to understand. That is too terse and I do not like jumping around to see examples and clarifications for each function. I enjoy the current style of your Lwt docs much more.
(The way I use these docs is to grep for a function name, then read all about it. I do not enjoy reading a description, then jumping to a linked example, then coming back to the description to have all the information.)
I find the general organisation and presentation of your Lwt docs very useful compared to most OCaml library docs I have seen. Also, your way of formulating the behaviour of functions is easy to understand for me (easier than Fpath for instance).
However, a list of functions somewhere (in the left bar, unfoldable?) would be nice.
Maybe but thatās not the single usage pattern you have to accommodate for.
I think a ābest of both worldsā approach might be to have folding before hitting the heavier documentation, rather than linking, which is more confusing. In the example docs, the first paragraph summarizes the function/type, and the next paragraphs go into more detail. If only the first paragraph was shown by default, but the rest was unfoldable, youād get the ability to easily find out more about those functions that interested you.
Linking would still be good for large topics that encompass many different functions/modules/types.
For the mlis themselves, many editors support automatic folding (e.g. vim uses {{{, and emacs can support it as well with a minor mode).
Folding is a good idea.
@antron, HTML has a tag for this: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details
Would you be able to put this in the appropriate places? E.g.,
<details>
<summary>`Lwt.pick ps` returns a promise that is pending until _one_ promise in the list `ps` becomes _resolved._</summary>
<p>When at least....</p>
</details>
Markdown supports HTML tags ā¦ although I donāt know if these docs are using Markdown for formatting.
The design of docs is clean and readable 
Below some constructive feedback:
Why is this useful?
I personally prefer a more authoritative style (instead of a self asked question).
Another good way to write Lwt.bind, that does not use the ppx, is with the >>= operator:
Why would I use this as opposed to the ārecommendedā PPX?
There seem to be different types of docs on one page (introduction, tutorials / guides, API / reference). I would prefer separate pages for each. The side menu makes it easy to quickly to go to the relevant page.
Apple developer docs might also be an interesting template. They have an intro about the class but do not provide a full tutorial there. They also allow clicking Topics to skip this part.
Elixir follows a similar pattern. They seem to try to keep the intro shortish. Also the side-menu with the functions index helps a lot.
Both have function indexes which help to give a quick overview of what is provided by the module (function names etc.).
Thanks for the feedback and suggestions 
I guess weāll be experimenting with layouts when writing the ārealā doc generator (the current postprocessor is full of hacks and not easy to edit).
@yawaramin, Iām using ocamldoc and regular ocamldoc formatting for now. Itās not a principled choice, though. I just used whatās available, to be able to focus on the content.
Ah, I see, you have a doc processor that converts the custom markup into HTML. One thing you could do is have a convention similar to a git commit message: that the first paragraph of the doc comment is treated as the summary line, and the remaining paragraphs are treated as the body of the documentation. Then, you could generate the <details> tag to hide the body by default and let the reader click through to see it.
All expanded/all hidden should (eventually) be a configurable option on the doc page, too.
Iām happy to help any way I can ā¦ I can probably start by doing code reviews. Ping me here or on GitHub if I can assist.
Cheers
Yep, the converter is the standard ocamldoc. The convention is a decent one, but Iād expect it will get annoying for APIs that only have, say, two paragraphs of docs, and the second one is not worth hiding (example).
IIRC Doxygen had @implementation for separating implementation from API docs. Maybe we can have the equivalent of a @details tag, making all following paragraphs get stuffed into <details>.
And thanks for the offer
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.