Respect original comment indentation for code blocks

[bobbypriam]

(I hope the title is clear enough.)

Basically code inside {[ ... ]} blocks are indented from the start of the line. It would be nicer if it can respect the indent of the first {[ token.

E.g. instead of having to write this:

(** A section of introduction.

    Some other introduction here, more and more sentences. The code block under
    this should be indented from the start:

{[
let foo = 10
let _ = print_endline (string_of_int foo)
]}

    Another sentence to close the introduction. *)

It would be great if we can write this:

(** A section of introduction.

    Some other introduction here, more and more sentences. Note that the code block
    has the same indentation as the other comments.

    {[
    let foo = 10
    let _ = print_endline (string_of_int foo)
    ]}

    Another sentence to close the introduction. *)

This is particularly annoying if we want to document an example of a function inside an inner module (2 or more indentation-level deep). Or was there another way of preferred docs indentation?

[aantron]

Agreed 100%, has been on my list for a long time, too :)

I would suggest to do the indentation from the left-most column of the code, so if someone has an instinct to write

(** A section of introduction.

    Some other introduction here, more and more sentences. Note that the code block
    has the same indentation as the other comments.

    {[
      let foo = 10
      let _ = print_endline (string_of_int foo)
    ]}

    Another sentence to close the introduction. *)

...the output will still be as they would expect.

[bobbypriam]

Great to hear! And yes using the left-most column also works and would be cleaner.

One thing to consider is whether we want the same behavior on verbatim blocks ({v ... v}). I'm guessing consistency would be preferred here, but I could be wrong.