Preserve code layout in .mli files

[aantron]

While writing the docs for Dream, I needed control over width. For example, this function

val run :
  ?interface:string ->
  ?port:int ->
  ?stop:unit promise ->
  ?debug:bool ->
  ?error_handler:error_handler ->
  ?secret:string ->
  ?old_secrets:string list ->
  ?prefix:string ->
  ?https:true ->
  ?certificate_file:string ->
  ?key_file:string ->
  ?builtins:bool ->
  ?greeting:bool ->
  ?adjust_terminal:bool ->
    handler -> unit

ought to be set like that, or in some similar way. By contrast, current odoc sets functions on one wrapped line no matter how wide the signature is. See here for an example. Ideally, I would have control over width even for the latter layout, the odoc default, but for Dream's two-column layout, width control is critical.

To work around this, Dream's doc generation process applies about 1400 lines of hand-written patches to odoc output.

It would be much more convenient if odoc would preserve the layout in the source to the greatest extent possible, since then the .mli file could be used to control and tweak the appearance of the docs.

[github-actions]

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.

[Julow]

Since #782, the run function renders like this:

val run : 
  ?interface:string ->
  ?port:int ->
  ?stop:unit promise ->
  ?debug:bool ->
  ?error_handler:error_handler ->
  ?secret:string ->
  ?old_secrets:string list ->
  ?prefix:string ->
  ?https:bool ->
  ?certificate_file:string ->
  ?key_file:string ->
  ?builtins:bool ->
  ?greeting:bool ->
  ?adjust_terminal:bool ->
  handler ->
  unit

I believe this is better than preserving the original formatting because it makes the documentation easier to read (more consistency, less different layouts to worry about).

[Julow]

I consider the automatic formatting better than the original source for consistency. Do you still need a hand-made patch in Dream ?

[aantron]

Thanks @Julow! The formatting you've shown is an improvement and I could consider switching to it. I'll try it out for Dream.

[aantron]

I've decided to stick with manual formatting in Dream for now, as I find that setting the result type with more indentation than the arguments is more legible, and also that a function with a lot of rarely-used optionals benefits from having the final foo -> bar -> baz on one line. I have, however, applied the new odoc formatting in Luv's docs, where I don't rewrite them, and this is a huge improvement!