Update vendored odoc-parser to version 2.4 (#2631)

* Backport the table feature from Odoc 2.4's parser and implement tables.

* Make sure elements in light table don't wrap

Invalid syntax was generated when elements had to wrap. This is fixed by
making sure all the elements in the table are inline elements and then
by formatting them without any break.

A smaller type is used to represent safely formattable light table that
do not contain any block elements.

The `~wrap` argument is added to `fmt_inline_elements` that controls
whether elements can wrap. This is passed explicitly rather than through
the config type to be sure that the information is not lost when
recursing through elements.
This fixed a potential bug in heading labels.

* Odoc 2.4's code blocks support delimiters and a output section.

* Add support for @hidden tag, quoted references and reduce diff with upstream

CHANGES.md

@@ -56,6 +56,8 @@ profile. This started with version 0.26.0.
 - Added back the flag `--disable-outside-detected-project` (#2439, @gpetiot)
   It was removed in version 0.22.
 
+- Support newer Odoc syntax (#2631, @Julow)
+
 ### Changed
 
 - \* Consistent formatting of comments (#2371, #2550, @Julow)

lib/Docstring.ml

@@ -9,6 +9,7 @@
 (*                                                                        *)
 (**************************************************************************)
 
+module Ast = Ocamlformat_odoc_parser.Ast
 module Odoc_parser = Ocamlformat_odoc_parser.Odoc_parser
 
 let parse ~loc text =
@@ -56,8 +57,6 @@ let odoc_reference = ign_loc str
 
 let option f fmt = function Some v -> f fmt v | None -> ()
 
-let pair fmt_a fmt_b fmt (a, b) = fpf fmt "(%a,%a)" fmt_a a fmt_b b
-
 let odoc_style fmt = function
   | `Bold -> fpf fmt "Bold"
   | `Italic -> fpf fmt "Italic"
@@ -88,15 +87,31 @@ let rec odoc_inline_element fmt = function
 and odoc_inline_elements fmt elems =
   list (ign_loc odoc_inline_element) fmt elems
 
+let light_heavy_to_string = function `Light -> "Light" | `Heavy -> "Heavy"
+
+let alignment_to_string = function
+  | `Left -> "Left"
+  | `Right -> "Right"
+  | `Center -> "Center"
+
+let header_data_to_string = function `Header -> "Header" | `Data -> "Data"
+
 let rec odoc_nestable_block_element c fmt = function
   | `Paragraph elms -> fpf fmt "Paragraph(%a)" odoc_inline_elements elms
-  | `Code_block (metadata, txt) ->
-      let txt = Odoc_parser.Loc.value txt in
-      let txt = c.normalize_code txt in
-      let fmt_metadata =
-        option (pair (ign_loc str) (option (ign_loc str)))
+  | `Code_block (b : Ast.code_block) ->
+      let fmt_metadata fmt (m : Ast.code_block_meta) =
+        fpf fmt "(%a, %a)" (ign_loc str) m.language
+          (option (ign_loc str))
+          m.tags
       in
-      fpf fmt "Code_block(%a, %a)" fmt_metadata metadata str txt
+      let fmt_content =
+        ign_loc (fun fmt s -> str fmt (c.normalize_code s))
+      in
+      let fmt_output =
+        option (list (ign_loc (odoc_nestable_block_element c)))
+      in
+      fpf fmt "Code_block(%a, %a, %a, %a)" (option fmt_metadata) b.meta
+        (option str) b.delimiter fmt_content b.content fmt_output b.output
   | `Math_block txt -> fpf fmt "Math_block(%a)" str txt
   | `Verbatim txt -> fpf fmt "Verbatim(%a)" str txt
   | `Modules mods -> fpf fmt "Modules(%a)" (list odoc_reference) mods
@@ -106,6 +121,18 @@ let rec odoc_nestable_block_element c fmt = function
         fpf fmt "Item(%a)" (odoc_nestable_block_elements c) elems
       in
       fpf fmt "List(%s,%a)" ord (list list_item) items
+  | `Table ((grid, alignment), syntax) ->
+      let pp_align fmt aln = fpf fmt "%s" (alignment_to_string aln) in
+      let pp_cell fmt (elems, header) =
+        fpf fmt "(%a,%s)"
+          (odoc_nestable_block_elements c)
+          elems
+          (header_data_to_string header)
+      in
+      let pp_grid = list (list pp_cell) in
+      let pp_alignment = option (list (option pp_align)) in
+      fpf fmt "Table((%a,%a),%s)" pp_grid grid pp_alignment alignment
+        (light_heavy_to_string syntax)
 
 and odoc_nestable_block_elements c fmt elems =
   list (ign_loc (odoc_nestable_block_element c)) fmt elems
@@ -135,6 +162,7 @@ let odoc_tag c fmt = function
   | `Inline -> fpf fmt "Inline"
   | `Open -> fpf fmt "Open"
   | `Closed -> fpf fmt "Closed"
+  | `Hidden -> fpf fmt "Hidden"
 
 let odoc_block_element c fmt = function
   | `Heading (lvl, lbl, content) ->