HTML page for functors is hard to comprehend.

[dbuenzli]

Since the page rendering adds non-user defined headings and the resulting signature is inlined it makes it for a confusing heading structure:

https://b0-system.github.io/odig/doc/asetmap/Asetmap/Set/Make/index.html (src)

Here are a few ideas:

1. Use heading h1 for Parameter and Signature (h1 is out of reach for ocamldoc users).
2. Wrap the current Parameters section in a div.odoc-parameters and follow with the inlined signature without adding the Signature heading; that is let the inlined sig define the rest of the page.
3. Increment headings up by one in the inlined signature (this is asking for trouble both rendering an UX wise).
4. Keep headings as is now but include the signature in an <article class="odoc-signature">

Both 4 and 3 are asking for stylesheet and rendering troubles. 1, 3 and 4 also ask a few questions for the page toc and consistency w.r.t. other pages.

Altogether I have the impression that the easiest and best would be 2.

[Drup]

I was also troubled by the rendering for functor page. I think I have tried or considered all of those at various points. Removing the Signature heading is actually really bad for readability, because the limit between parameters and signature becomes unclear. Maybe the best is to insert the Signature heading only if there is no such heading in the documentation.

[dbuenzli]

Removing the Signature heading is actually really bad for readability, because the limit between parameters and signature becomes unclear.

That's the point of:

2. Wrap the current Parameters section in a div.odoc-parameters

It then becomes possible to do something stylewise with either .odoc-parameters + * and/or .odoc-parameters itself to properly delineate the parameters block

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. The main purpose of this is to keep the issue tracker focused to what is actively being worked on, so that the amount and variety of open yet inactive issues does not overwhelm contributors.

An issue closed as stale is not rejected — further discussion is welcome in its closed state, and it can be resurrected at any time. odoc maintainers regularly check issues that were closed as stale in the past, to see if the time is right to reopen and work on them again. PRs addressing issues closed as stale are as welcome as PRs for open issues. They will be given the same review attention, and any other help.