Comment author: @dbuenzli

Personally I don't feel this would improve documentation usability.

Comment author: @yawaramin

I think it's a good compromise between the current layout and what you suggested in https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/2?u=yawaramin :

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.

So what I'm proposing is we don't need to change any current docstrings, and instead provide a quick overview with links so the reader can jump down to these descriptions. It solves the problem (at least to some extent) you identified:

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.

With an overview section of just names and descriptions, the interaction pattern is quickly scanning to find exactly what you were looking for, and then jumping down to the details if necessary. It's functionally equivalent to your proposed interaction.

Comment author: @xavierleroy

@yawaramin: the best way to go is to submit your work as a Github pull request when it is ready.

Comment author: @yawaramin

@xLeroy: thanks, I'm planning to send a PR very soon. For best results, I want to wait for #7635 , octachron is working on generating linkable IDs for modules and module types. The table of contents I have so far is nice but it will be even nicer with that.

Comment author: @yawaramin

PR sent #1385

Comment author: @dbuenzli

@yawaramin In my opinion the problem there stems from trying to mix a manual with API reference. As such I rather see it as a problem with the approach taken in documenting that library rather than ocamldoc's markup itself.

In some sense if your functions need loads of text to describe what they are doing you should rather revise your API... The current layout works well for the M.t pattern and in most cases, it has a good scrolling/scanning/access to details efficiency.

What you suggest will in my opinion add more noise for small to medium size modules and also destroy a few useful interaction that are available in the current layout (e.g. in-page browser search takes you directly to the full description of a given symbol with high probability).

It is possible to section your symbols by functionality and nothing prevents you from providing direct links to the section in a well-designed and written module introduction which may work better than a per symbol toc.

Comment author: @yawaramin

@dbuenzli I agree with your concerns about increasing the noise level for small-to-medium modules and preserving in-page search interaction. Please take a look at https://discuss.ocaml.org/t/proposal-ocamldoc-should-generate-a-table-of-contents-in-each-module-page/871?u=yawaramin , I believe by putting the module TOC in a (by default collapsed) expandable section, I address both the concerns.

Re: mixing manual with API reference and designing module documentation, I believe module docs are our best hope of encouraging developers to write good docs, be they manual style, tutorial style, or API reference style. The easier we make it for them, the more everyone benefits. This is more of a philosphical argument though, for now you can check out the above link to see where I want to take ocamldoc output in the medium term.

This issue has been open one year with no activity. Consequently, it is being marked with the "stale" label. What this means is that the issue will be automatically closed in 30 days unless more comments are added or the "stale" label is removed. Comments that provide new information on the issue are especially welcome: is it still reproducible? did it appear in other contexts? how critical is it? etc.