### Author:  [@antron](https://discuss.ocaml.org/u/antron)
#### Post date: [September 6, 2017, 10:55am UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/1 "2017-09-06T10:55:05Z")
See the new docs [here](https://ocsigen.github.io/lwt/manual-draft/Lwt.html) š
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](https://github.com/ocsigen/lwt/projects/2) for an overview of the whole undertaking.
All feedback is welcome š Please comment here, or review in the GitHub pull request:
>
---
### Author:  [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)
#### Post date: [September 6, 2017, 12:42pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/2 "2017-09-06T12:42:10Z")
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`](http://erratique.ch/software/fpath/doc/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.
---
### Author:  [@antron](https://discuss.ocaml.org/u/antron)
#### Post date: [September 6, 2017, 1:38pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/3 "2017-09-06T13:38:17Z")
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.
---
### Author:  [@bobbypriambodo](https://discuss.ocaml.org/u/bobbypriambodo)
#### Post date: [September 6, 2017, 2:13pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/4 "2017-09-06T14:13:35Z")
> [@dbuenzli](#):
>
> This makes it difficult to navigate the API and see what it actually offers
The way Elixir docs handle this is to put a [Summary](https://hexdocs.pm/ecto/Ecto.Repo.html#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 `mli`s directly. But perhaps itās better to direct people to some online docs with navigation rather than the `mli`s 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ā¦
---
### Author:  [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)
#### Post date: [September 6, 2017, 2:47pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/5 "2017-09-06T14:47:13Z")
> [@bobbypriambodo](#):
>
> 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](http://docs.mirage.io/) or treat your opam switch with [`odig`](http://erratique.ch/software/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.
---
### Author:  [@bobbypriambodo](https://discuss.ocaml.org/u/bobbypriambodo)
#### Post date: [September 6, 2017, 3:00pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/6 "2017-09-06T15:00:29Z")
> [@dbuenzli](#):
>
> odoc supports this, see [docs.mirage.io](http://docs.mirage.io)
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)?
---
### Author:  [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)
#### Post date: [September 6, 2017, 3:04pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/7 "2017-09-06T15:04:32Z")
> [@bobbypriambodo](#):
>
> 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`.
---
### Author:  [@Ronan](https://discuss.ocaml.org/u/Ronan)
#### Post date: [September 6, 2017, 3:25pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/8 "2017-09-06T15:25:30Z")
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.
---
### Author:  [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)
#### Post date: [September 6, 2017, 3:53pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/9 "2017-09-06T15:53:54Z")
> [@Ronan](#):
>
> The way I use these docs is to grep for a function name, then read all about it
Maybe but thatās not the single usage pattern you have to accommodate for.
---
### Author:  [@bluddy](https://discuss.ocaml.org/u/bluddy)
#### Post date: [September 6, 2017, 6:10pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/10 "2017-09-06T18:10:59Z")
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).
---
### Author:  [@yawaramin](https://discuss.ocaml.org/u/yawaramin)
#### Post date: [September 6, 2017, 6:39pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/11 "2017-09-06T18:39:51Z")
Folding is a good idea.
@antron, HTML has a tag for this: [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details)
Would you be able to put this in the appropriate places? E.g.,
```auto
`Lwt.pick ps` returns a promise that is pending until _one_ promise in the list `ps` becomes _resolved._
When at least....
```
Markdown supports HTML tags ā¦ although I donāt know if these docs are using Markdown for formatting.
---
### Author:  [@DerRechner](https://discuss.ocaml.org/u/DerRechner)
#### Post date: [September 6, 2017, 8:03pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/12 "2017-09-06T20:03:02Z")
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](https://developer.apple.com/documentation/uikit/uiview) 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](https://hexdocs.pm/elixir/Map.html) 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.).
---
### Author:  [@antron](https://discuss.ocaml.org/u/antron)
#### Post date: [September 8, 2017, 10:17am UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/13 "2017-09-08T10:17:40Z")
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](https://github.com/aantron/lwt-manual/blob/master/postprocess.ml)).
@yawaramin, Iām using ocamldoc and regular [ocamldoc formatting](https://github.com/ocsigen/lwt/blob/aa8bf8d73ddce76a3f647035df1b6cdf04314898/src/core/lwt.mli#L94-L107) for now. Itās not a principled choice, though. I just used whatās available, to be able to focus on the content.
---
### Author:  [@yawaramin](https://discuss.ocaml.org/u/yawaramin)
#### Post date: [September 8, 2017, 9:10pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/14 "2017-09-08T21:10:35Z")
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 `` 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
---
### Author:  [@antron](https://discuss.ocaml.org/u/antron)
#### Post date: [September 8, 2017, 10:38pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/15 "2017-09-08T22:38:35Z")
Yep, the converter is the standard [`ocamldoc`](http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html). 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](https://ocsigen.github.io/lwt/manual-draft/Lwt.html#VALpause)).
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 ``.
And thanks for the offer š
---
### Author:  [@antron](https://discuss.ocaml.org/u/antron)
#### Post date: [October 12, 2017, 5:20pm UTC](https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/16 "2017-10-12T17:20:32Z")
Thanks for the reviews, suggestions, discussion! The PR is [moving along](https://github.com/ocsigen/lwt/pull/469#issuecomment-336201131) to merge, and there is a slightly updated version of the docs [now online](https://ocsigen.github.io/lwt/manual-draft/Lwt.html).
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, `` etc. Iāll think a lot about the presentation and experiment with it. Also, @yawaramin, glad to see the [ocamldoc TOC PR](https://github.com/ocaml/ocaml/pull/1385) 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.