What the work ran into
lukstafi#669 made dune build @fmt a per-PR CI gate (gh-ocannl-938). Its first run on the branch was red on a genuinely unformatted comment, and finding that fact in the job log meant filtering out ~60 lines of ocamlformat's odoc parser warnings first (Warning: Invalid documentation comment: ... End of text is not allowed in '[...]' (code) and friends). On a clean master today the same run prints 22 such warnings from 9 files:
arrayjit/lib/autotune.mli:276 Paragraph should begin on its own line
arrayjit/lib/schedule.mli:31,70,91,392 End of text is not allowed in '[...]' (code)
arrayjit/lib/schedule.mli:365,369,385 Blank line is not allowed in '[...]' (code)
arrayjit/lib/tnode.ml:458 Paragraph should begin on its own line
tensor/einsum_types.ml:39 End of text is not allowed in '[...]' (code)
tensor/operation.ml:913 End of text is not allowed in '[...]' (code)
test/einsum/test_closing_order.ml:4,5,8,18,20 '{3 ...}' headings mid-line, '{3' without a following space
test/operations/shell_scripts_parse.ml:149,151,499
test/support/codegen_text_scan.ml:34 Unpaired ']' (end of code)
test/support/dune_stanza_scan.ml:1986 '{b' should be followed by space
Each is a real doc-comment syntax slip (an unclosed [, a blank line inside [...], a {3 heading in the middle of a paragraph), so odoc renders those comments wrong too; ocamlformat keeps formatting the file and only warns.
Why it is worth fixing
Every PR's fmt job now carries this noise, and it is exactly what a reader has to scroll past to reach the diff the gate is red for. It also grows silently: nothing fails on a new one, so the count only goes up. Root dune already treats the WORSE ocamlformat refusal (warning 50, misplaced doc comments) as a compile error at the site; these are the softer class.
What a fix would touch
Fix the 22 sites by hand (each is one or two characters or a line break), then decide whether to hold the count at zero: ocamlformat has no flag to promote these to errors, so the options are a dune build @fmt 2>&1 | grep -c "Invalid documentation comment" step in the fmt job that fails on a nonzero count, or dune build @doc with odoc warnings as errors on the CI leg that already builds docs (gh-pages-api.yml), which would catch the same class at the source. The count-in-CI step is the smaller change and matches what the gate's log reader actually needs.
What the work ran into
lukstafi#669 made
dune build @fmta per-PR CI gate (gh-ocannl-938). Its first run on the branch was red on a genuinely unformatted comment, and finding that fact in the job log meant filtering out ~60 lines of ocamlformat's odoc parser warnings first (Warning: Invalid documentation comment: ... End of text is not allowed in '[...]' (code)and friends). On a clean master today the same run prints 22 such warnings from 9 files:Each is a real doc-comment syntax slip (an unclosed
[, a blank line inside[...], a{3heading in the middle of a paragraph), so odoc renders those comments wrong too; ocamlformat keeps formatting the file and only warns.Why it is worth fixing
Every PR's
fmtjob now carries this noise, and it is exactly what a reader has to scroll past to reach the diff the gate is red for. It also grows silently: nothing fails on a new one, so the count only goes up. Rootdunealready treats the WORSE ocamlformat refusal (warning 50, misplaced doc comments) as a compile error at the site; these are the softer class.What a fix would touch
Fix the 22 sites by hand (each is one or two characters or a line break), then decide whether to hold the count at zero: ocamlformat has no flag to promote these to errors, so the options are a
dune build @fmt 2>&1 | grep -c "Invalid documentation comment"step in thefmtjob that fails on a nonzero count, ordune build @docwith odoc warnings as errors on the CI leg that already builds docs (gh-pages-api.yml), which would catch the same class at the source. The count-in-CI step is the smaller change and matches what the gate's log reader actually needs.