Surprising position of a paragraph after a tag

[gpetiot]

Hi, we have encountered a surprising behavior after using odoc-parser 0.9.0 (ocaml-ppx/ocamlformat#1719), it looks like after parsing a tag, the following paragraphs are added to the list of paragraphs of said tag.

There is a corresponding test in odoc-parser's testbase:

odoc-parser/test/test.ml

Lines 3537 to 3546 in c5ce41b

	let paragraphs =
	test "@deprecated foo\n\nbar";
	[%expect
	{|
	((output
	(((f.ml (1 0) (3 3))
	(@deprecated
	((f.ml (1 12) (1 15)) (paragraph (((f.ml (1 12) (1 15)) (word foo)))))
	((f.ml (3 0) (3 3)) (paragraph (((f.ml (3 0) (3 3)) (word bar)))))))))
	(warnings ())) |}]

Is this really expected or should it be 2 different items in the odoc AST?

[jonludlam]

Looking at the docs here it seems that the @deprecated tag is followed by text which includes blank lines separating paragraphs. My reading of that is that the test case is correct - what do you think?

[gpetiot]

I had the feeling (and some other people too, based on the way they wrote their doc comments) that since the bar line was separated with 2 linebreaks from the @deprecated foo tag (and indented on the same column, but I don't know if relevant), then it would be considered a different item instead of being a child of this tag.

@deprecated foo
      bar                       // same item

@deprecated foo

bar                     // different item

Or maybe there is something in the odoc grammar to indicate the end of a paragraph attached to a tag?

[jonludlam]

It seems to me that the expectation is that tags are at the end of doc comments - see the comment here. As such I think there's no way to return a result looking like [ Paragraph _; Tag _; Paragraph _ ]

[gpetiot]

Alright if that's expected I'm happy to close this issue then, thanks!