Better indentation for lists in comments

[yminsky]

Right now, lists in comments are indented as follows:

(**
    - this is a
    multi-line element of a list.
    - and this is a one-liner
*)

But it would be better if it implemented like this:

(**
    - this is a
      multi-line element of a list.
    - and this is a one-liner
*)

Is that something we can change?

[AltGr]

It's certainly possible, but may become a bit awkward code-wise since we don't tokenise the comments at the moment (except for ocamldoc snippets: {v v}, {[ ]}, etc.)

Note that, by default, ocp-indent leaves indentation semi-free within comments: the left margin must be respected, but additional indentation is preserved. This makes it less of a problem, because it at least preserves the second formatting above when you did it manually. The JaneStreet defaults, however, enforce option strict_comments, which disables this behaviour.

Note also that we already align * to allow this pattern:

(**
 * - this is a
 *   multi-line element of a list.
 * - and this is a one-liner
*)

so maybe it wouldn't be that complicated, and I have just been afraid by the complexity of github's markdown list parsing :)

[yminsky]

For doc comments, it seems preferable for the indentation to show the structure as understood by the doc-generation toolchain, since otherwise people can do confusing things in the source that look like they will show up in the generated docs, but won't. i.e., if they write:

(**
   - This is a nested list
       - and this is
       - a sublist
   - back at the toplevel
 *)

It seems like a clarifying service for ocp-indent to convert it to this:

(**
   - This is a nested list
   - and this is
   - a sublist
   - back at the toplevel
 *)

If someone really wants the literal fixed-width text behavior, they can always say so:

(**
   {v     
   - This is a nested list
       - and this is
       - a sublist
   - back at the toplevel
   v}
 *)

And ocp-indent won't object.

All in, I think supporting this is worth it, and happily, the conventions of ocaml's documentation comments are a hell of a lot simpler than the ones in markdown, so I doubt you'll end up with a parser anywhere near as complicated.

[yminsky]

Ping. Any thoughts on this issue?

[AltGr]

I'll try to find the time to get back into ocp-indent's parser and see how this could fit.

[yminsky]

Thanks!

[yminsky]

Ping.