Document how to escape arbitrary text for a doc comment

[DemiMarie]

When adding more protocols to @talex5’s pure-OCaml Wayland implementation, I found that building certain protocols failed. In one case, this turned out to be because the code generator copies a free-form description from the XML source into a documentation comment, and the XML contained *), which was interpreted as a close comment by OCaml.

There are many hacky ways to solve the issue, but I’d like to know what the proper way to solve it is.

[panglesd]

I think the best way would be if OCaml could escape it, and pass it to odoc directly in the *) form. That could be an issue for ocaml/ocaml.

Currently, I don't know if there is a proper way. We need a way to escape it in odoc, that also escapes it in OCaml. What are the hacky ways you found?

My editor is putting *\) when commenting a region that contains *). Maybe adding ")" to the list of character we escape could be the proper way you are looking for?
(This escaping would need to be generalized inside code spans/blocks/verbatim, which is not ideal).

[DemiMarie]

I think the best way would be if OCaml could escape it, and pass it to odoc directly in the *) form. That could be an issue for ocaml/ocaml.

Do you mean unescape?

This is generated code, and I don’t think the comments follow any particular markup language.

Currently, I don't know if there is a proper way. We need a way to escape it in odoc, that also escapes it in OCaml. What are the hacky ways you found?

The hacky solution is to mangle the input in some way.

My editor is putting *\) when commenting a region that contains *). Maybe adding ")" to the list of character we escape could be the proper way you are looking for? (This escaping would need to be generalized inside code spans/blocks/verbatim, which is not ideal).

That still runs into OCaml strings being interpreted inside comments. I’m not sure what the best solution to that is.

[Julow]

OCaml supports escaping in comments using the string literal syntaxes:

(**
  "*)"

  {delim|
   *)
   |}
  |delim}
 *)

Perhaps Odoc should parse that and turn it into a code span or code block ?