See the new docs here :slight_smile: [02] 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 :slight_smile: Please comment here, or review in …

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 optimi…

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…

[image] 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 (an example module, Ecto.Repo) after the overview in the generated docs, which only enumerates defined types and functions of a module. Elixir folk…

[image] 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 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 setti…

[image] dbuenzli: odoc supports this, see 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 pa…

[image] 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.

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, the…

[image] 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.

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 wa…

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` beco…

First installment of Lwt's new manual

Ecosystem

dbuenzli September 6, 2017, 3:04pm 7

Ah yes sorry, I thought you meant simply linking to definitions on the pages. No, full code browsing is not supported by odoc.

What is the reason of separation of module implementation and signatures in OCaml?

Topic		Replies	Views
Why the OCaml ecosystem is poorly documented? Community	61	3500	January 29, 2025
OCaml Documentation Open Thread Ecosystem	148	10746	October 13, 2018
New pages for OCaml API Community	39	3125	March 28, 2020
Suggestions for ocaml documentation Community documentation , ocamlorg	84	7719	July 16, 2020
2025 Documentation best practices Ecosystem documentation	36	1204	August 4, 2025

First installment of Lwt's new manual

Related topics