Incorrect rejection of `{[ ]}` docstring

[jberdine]

Code such as:

type sp =
  | Blank  (** {[ ]} *)

leads to a warning such as

Warning: Invalid documentation comment:
File "lib/Fmt.mli", line 23, characters 15-20:
'{[...]}' (code block) should not be empty.

There isn't any indication in the spec that the "preformatted source code style" should not be a single space. And for the warning in particular, being preformatted, a single space is not empty.

[dbuenzli]

If you need a solution now you can likely use a non-breaking space (U+00A0) to work around (didn't try, but that usually works most of the time when you hit silly things like that).

[Julow]

Odoc's spec is not exactly ocamldoc's one and there's no written spec currently. The warning is from Odoc's parser, which strip the spaces. It is possible to fix this in Odoc by moving this check further in the pipeline (there's already a place for these checks) or removing it completely.

[jberdine]

you can likely use a non-breaking space (U+00A0) to work around

Thanks @dbuenzli, that is helpful.

[jberdine]

Odoc's spec is not exactly ocamldoc's one and there's no written spec currently.

The situation where odoc consciously disagrees with the OCaml manual, and doesn't have a spec itself, is a continuing issue. Are there any plans in this ?

[Drup]

It is possible to fix this in Odoc by moving this check further in the pipeline (there's already a place for these checks) or removing it completely.

Wait, you closed this a a bit quickly. This issue has a point: I don't really see the purpose of this check and it probably shouldn't be there.

[Julow]

Wait, you closed this a a bit quickly

Indeed ! Sorry about that. I thought I was reading an issue on OCamlformat's repository.

[asavahista]

is there a usecase for a codeblock containing a single space, given that it's indistinguishable from a blank line? ([ ] would be distinguishable from [] though) maybe jberdine wants an inline preformatted code span rather than a code block, which i don't believe exists currently?

[jberdine]

There is a need for both "preformatted" elements, {[...]} in ocamldoc, and (not preformatted) "code" elements, [...] in ocamldoc. It seems that odoc makes a distinction between "inline" and non-inline (is this the same as the "span" vs "block" distinction), and interprets ocamldoc's "preformatted" as "non-inline", and "non-preformatted" as "inline".

My understanding is that the tension is conflating preformatted vs not with non-inline vs not, and that at least preformatted and non-preformatted possibly inline elements are needed. In the context of ocamlformat we should leave preformatted elements as they are, but format the non-preformatted ones. Whether they are inline or not is not as important in this context, as the non-preformatted ones will be broken across lines if they are long. But the formatting shouldn't break/change the odoc parsed form, which highlights the tension.

I wonder if it would be feasible to extend odoc's parse tree to be able to express both preformatted vs not and inline vs not, and to use {[...]} for preformatted and [...] for non-preformatted, and to identify non-inline elements as those without newlines after [ and before ], probably modulo whitespace.