Depend on odoc-parser instead of odoc (#1683)

Author: kit-ty-kate

CHANGES.md

@@ -45,6 +45,9 @@
 
   + Improve position of `;;` tokens (#1688, @gpetiot)
 
+  + Depend on `odoc-parser` instead of `odoc` (#1683, @kit-ty-kate, @jonludlam)
+    The parser from odoc has been split from the main odoc package and put into its own package, `odoc-parser`.
+
 #### New features
 
   + Implement OCaml 4.13 features

dune-project

@@ -61,8 +61,8 @@
    (and
     :with-test
     (>= 2.5.0)))
-  (odoc
-   (>= 1.4.2))
+  (odoc-parser
+   (>= 0.9.0))
   re
   (stdio
    (< v0.15))
@@ -104,8 +104,8 @@
    (and
     :with-test
     (>= 2.5.0)))
-  (odoc
-   (>= 1.4.2))
+  (odoc-parser
+   (>= 0.9.0))
   re
   (stdio
    (< v0.15))

lib/Docstring.ml

@@ -15,13 +15,11 @@ let parse ~loc text =
     { location with
       pos_cnum= location.pos_cnum + 3 (* Length of comment opening *) }
   in
-  match Odoc_parser.parse_comment_raw ~location ~text with
-  | exception _ ->
-      let span = Migrate_ast.Location.to_span loc in
-      Error [Odoc_model.Error.make "comment could not be parsed" span]
-  | {value; warnings= []} -> Ok value
-  | {warnings; _} -> Error warnings
+  let v = Odoc_parser.parse_comment ~location ~text in
+  match Odoc_parser.warnings v with
+  | [] -> Ok (Odoc_parser.ast v)
+  | warnings -> Error warnings
 
 let warn fmt warning =
   Format.fprintf fmt "Warning: Invalid documentation comment:@,%s\n%!"
-    (Odoc_model.Error.to_string warning)
+    (Odoc_parser.Warning.to_string warning)

lib/Docstring.mli

@@ -12,6 +12,6 @@
 val parse :
      loc:Warnings.loc
   -> string
-  -> (Odoc_parser.Ast.docs, Odoc_model.Error.t list) Result.t
+  -> (Odoc_parser.Ast.t, Odoc_parser.Warning.t list) Result.t
 
-val warn : Format.formatter -> Odoc_model.Error.t -> unit
+val warn : Format.formatter -> Odoc_parser.Warning.t -> unit

lib/Fmt_odoc.ml

@@ -11,7 +11,7 @@
 
 open Fmt
 open Odoc_parser.Ast
-module Location_ = Odoc_model.Location_
+module Loc = Odoc_parser.Loc
 
 type conf = {fmt_code: string -> (Fmt.t, unit) Result.t}
 
@@ -56,7 +56,7 @@ let str_normalized ?(escape = escape_all) s =
   |> List.filter ~f:(Fn.non String.is_empty)
   |> fun s -> list s "@ " (fun s -> escape s |> str)
 
-let ign_loc ~f with_loc = f with_loc.Location_.value
+let ign_loc ~f with_loc = f with_loc.Loc.value
 
 let fmt_verbatim_block s =
   let force_break = String.contains s '\n' in
@@ -67,8 +67,9 @@ let fmt_verbatim_block s =
   in
   hvbox 0 (wrap "{v" "v}" content)
 
-let fmt_code_block conf s =
-  match conf.fmt_code s with
+let fmt_code_block conf _s1 s2 =
+  let s2 = Odoc_parser.Loc.value s2 in
+  match conf.fmt_code s2 with
   | Ok formatted -> hvbox 0 (wrap "{[@;<1 2>" "@ ]}" formatted)
   | Error () ->
       let fmt_line ~first ~last:_ l =
@@ -77,7 +78,7 @@ let fmt_code_block conf s =
         else if String.length l = 0 then str "\n"
         else fmt "@," $ str l
       in
-      let lines = String.split_lines s in
+      let lines = String.split_lines s2 in
       let box = match lines with _ :: _ :: _ -> vbox 0 | _ -> hvbox 0 in
       box (wrap "{[@;<1 2>" "@ ]}" (vbox 0 (list_fl lines fmt_line)))
 
@@ -89,7 +90,7 @@ let fmt_reference = ign_loc ~f:str_normalized
 let list_should_use_heavy_syntax items =
   let heavy_nestable_block_elements = function
     (* More than one element or contains a list *)
-    | [{Location_.value= `List _; _}] | _ :: _ :: _ -> true
+    | [{Loc.value= `List _; _}] | _ :: _ :: _ -> true
     | [] | [_] -> false
   in
   List.exists items ~f:heavy_nestable_block_elements
@@ -107,10 +108,10 @@ let block_element_should_break elem next =
    depending on [block_element_should_break] *)
 let list_block_elem elems f =
   list_pn elems (fun ~prev:_ elem ~next ->
-      let elem = elem.Location_.value in
+      let elem = elem.Loc.value in
       let break =
         match next with
-        | Some {Location_.value= n; _}
+        | Some {Loc.value= n; _}
           when block_element_should_break
                  (elem :> block_element)
                  (n :> block_element) ->
@@ -120,8 +121,7 @@ let list_block_elem elems f =
       in
       f elem $ break )
 
-let space_elt : inline_element with_location =
-  Location_.(at (span []) (`Space ""))
+let space_elt : inline_element with_location = Loc.(at (span []) (`Space ""))
 
 let rec fmt_inline_elements elements =
   let wrap_elements opn cls ~always_wrap hd = function
@@ -173,7 +173,7 @@ let rec fmt_inline_elements elements =
 
 and fmt_nestable_block_element c = function
   | `Paragraph elems -> fmt_inline_elements elems
-  | `Code_block s -> fmt_code_block c s
+  | `Code_block (s1, s2) -> fmt_code_block c s1 s2
   | `Verbatim s -> fmt_verbatim_block s
   | `Modules mods ->
       hovbox 0
@@ -251,7 +251,7 @@ let fmt_block_element c = function
   | #nestable_block_element as elm ->
       hovbox 0 (fmt_nestable_block_element c elm)
 
-let fmt ~fmt_code (docs : docs) =
+let fmt ~fmt_code (docs : t) =
   vbox 0 (list_block_elem docs (fmt_block_element {fmt_code}))
 
 let diff c x y =
@@ -262,6 +262,4 @@ let diff c x y =
   Set.symmetric_diff (norm x) (norm y)
 
 let is_tag_only =
-  List.for_all ~f:(function
-    | {Location_.value= `Tag _; _} -> true
-    | _ -> false )
+  List.for_all ~f:(function {Loc.value= `Tag _; _} -> true | _ -> false)

lib/Fmt_odoc.mli

@@ -10,13 +10,11 @@
 (**************************************************************************)
 
 val fmt :
-     fmt_code:(string -> (Fmt.t, unit) Result.t)
-  -> Odoc_parser.Ast.docs
-  -> Fmt.t
+  fmt_code:(string -> (Fmt.t, unit) Result.t) -> Odoc_parser.Ast.t -> Fmt.t
 
 val diff :
   Conf.t -> Cmt.t list -> Cmt.t list -> (string, string) Either.t Sequence.t
 (** Difference between two lists of doc comments. *)
 
-val is_tag_only : Odoc_parser.Ast.docs -> bool
+val is_tag_only : Odoc_parser.Ast.t -> bool
 (** [true] if the documentation only contains tags *)

lib/Migrate_ast.ml

@@ -46,8 +46,6 @@ module Position = struct
   include (val Comparator.make ~compare ~sexp_of_t)
 
   let distance p1 p2 = p2.pos_cnum - p1.pos_cnum
-
-  let to_point x = Odoc_model.Location_.{line= x.pos_lnum; column= column x}
 end
 
 module Location = struct
@@ -110,12 +108,6 @@ module Location = struct
     let min a b = if width a < width b then a else b in
     List.reduce_exn (loc :: stack) ~f:min
 
-  let to_span loc =
-    let open Odoc_model.Location_ in
-    { file= loc.loc_start.pos_fname
-    ; start= Position.to_point loc.loc_start
-    ; end_= Position.to_point loc.loc_end }
-
   let of_lexbuf (lexbuf : Lexing.lexbuf) =
     { loc_start= lexbuf.lex_start_p
     ; loc_end= lexbuf.lex_curr_p

lib/Migrate_ast.mli

@@ -78,8 +78,6 @@ module Location : sig
 
   val is_single_line : t -> int -> bool
 
-  val to_span : t -> Odoc_model.Location_.span
-
   val of_lexbuf : Lexing.lexbuf -> t
 
   val print : Format.formatter -> t -> unit

lib/Normalize.ml

@@ -57,12 +57,10 @@ let list f fmt l =
 
 let str fmt s = Format.fprintf fmt "%s" (comment s)
 
-let ign_loc f fmt with_loc = f fmt with_loc.Odoc_model.Location_.value
+let ign_loc f fmt with_loc = f fmt with_loc.Odoc_parser.Loc.value
 
 let fpf = Format.fprintf
 
-open Odoc_parser.Ast
-
 let odoc_reference = ign_loc str
 
 let odoc_style fmt = function
@@ -101,7 +99,8 @@ let rec odoc_nestable_block_element c fmt = function
          only depend on linebreaks, which may be changed by the
          formatting. *)
       odoc_inline_elements fmt elms
-  | `Code_block txt ->
+  | `Code_block (_, txt) ->
+      let txt = Odoc_parser.Loc.value txt in
       let txt =
         try
           let ({ast; comments; _} : _ Parse_with_comments.with_comments) =
@@ -167,17 +166,17 @@ let odoc_block_element c fmt = function
       let lbl = match lbl with Some lbl -> lbl | None -> "" in
       fpf fmt "Heading(%s,%a,%a)" lvl str lbl odoc_inline_elements content
   | `Tag tag -> fpf fmt "Tag(%a)" (odoc_tag c) tag
-  | #nestable_block_element as elm -> odoc_nestable_block_element c fmt elm
+  | #Odoc_parser.Ast.nestable_block_element as elm ->
+      odoc_nestable_block_element c fmt elm
 
 let odoc_docs c fmt elems = list (ign_loc (odoc_block_element c)) fmt elems
 
 let docstring c text =
   if not c.conf.parse_docstrings then comment text
   else
     let location = Lexing.dummy_pos in
-    let parsed = Odoc_parser.parse_comment_raw ~location ~text in
-    Format.asprintf "Docstring(%a)%!" (odoc_docs c)
-      parsed.Odoc_model.Error.value
+    let parsed = Odoc_parser.parse_comment ~location ~text in
+    Format.asprintf "Docstring(%a)%!" (odoc_docs c) (Odoc_parser.ast parsed)
 
 let sort_attributes : attributes -> attributes =
   List.sort ~compare:Poly.compare

lib/dune

@@ -22,8 +22,7 @@
   ocaml_413
   ocamlformat_stdlib
   ocp-indent.lib
-  odoc.model
-  odoc.parser
+  odoc-parser
   parse_wyc
   re
   uuseg