ocaml / odoc

Documentation compiler for OCaml and Reason
Other
321 stars 90 forks source link

Doc comments with `*` at the beginning of each lines. #1224

Open panglesd opened 1 week ago

panglesd commented 1 week ago

I've seen several libraries use this style of comments:

    (** [decode_float dec buff ofs len] decodes [len] samples in each channel and puts
      * the result in [buff] starting at position [ofs].
      * @raise Hole_in_data if there was an interruption of the data.
      * @raise Invalid_parameters if all the data cannot fit in the buffer starting at the given position.
      *)

However, the * at the beginning of lines confuse odoc. Should this be dealt in the odoc parser, or upstream in OCaml?

Here are some examples, taken from @jonludlam's list in #1138:

gpetiot commented 6 days ago

I'm in favor of doing this in the ocaml parser directly. This would also make ocamlformat's job easier (assuming there is a flag to tell us whether there is a column of * to be printed or not).

panglesd commented 6 days ago

I think that's a good argument to do it in the ocaml parser. That might complicate upstream though, we should ask what the maintainers think.