Fix issue #865

CHANGES.md

@@ -1,10 +1,14 @@
 # Unreleased
 
+### Added
 - Support for OxCaml unboxed named types (@art-w, #1407)
 - Support for OxCaml zero alloc definitions (@Leonidas-from-XIV, #1422, #1444)
 - Remove requirement for ppx_expect in tests (@jonludlam, #1445)
 - Support for OxCaml modalities (@art-w, #1420)
 
+### Fixed
+- Allow to break link into multiline (@Tim-ats-d, #1439)
+
 # 3.2.1
 
 ### Fixed

src/parser/syntax.ml

@@ -1,3 +1,4 @@
+
 (* This module is a recursive descent parser for the ocamldoc syntax. The parser
    consumes a token stream of type [Token.t Stream.t], provided by the lexer,
    and produces a comment AST of the type defined in [Parser_.Ast].
@@ -167,6 +168,30 @@ type token_that_always_begins_an_inline_element =
   | `Begin_link_with_replacement_text of string
   | `Math_span of string ]
 
+let escape_link link =
+  let link = String.trim link in
+  let buf = Buffer.create (String.length link) in
+  let last_state =
+    String.fold_left
+         (fun state chr ->
+           match (state, chr) with
+           | `Char, '\\' -> `Backslash
+           | `Char, _ ->
+               Buffer.add_char buf chr;
+               `Char
+           | (`Backslash | `Escaping), (' ' | '\t' | '\n') -> `Escaping
+           | (`Backslash | `Escaping), _ ->
+               Buffer.add_char buf chr;
+               `Char)
+         `Char link
+  in
+  let () =
+    match last_state with
+    | `Backslash -> Buffer.add_char buf '\\'
+    | `Escaping | `Char -> ()
+  in
+  Buffer.contents buf
+
 (* Check that the token constructors above actually are all in [Token.t]. *)
 let _check_subset : token_that_always_begins_an_inline_element -> Token.t =
  fun t -> (t :> Token.t)
@@ -269,7 +294,7 @@ let rec inline_element :
   | `Simple_link u ->
       junk input;
 
-      let u = String.trim u in
+      let u = escape_link u |> String.trim in
 
       if u = "" then
         Parse_error.should_not_be_empty
@@ -281,7 +306,7 @@ let rec inline_element :
   | `Begin_link_with_replacement_text u as parent_markup ->
       junk input;
 
-      let u = String.trim u in
+      let u = escape_link u |> String.trim in
 
       if u = "" then
         Parse_error.should_not_be_empty

test/model/semantics/expected/heading.expected

@@ -174,6 +174,13 @@ foo
 --- output ---
 {"value":[{"`Heading":[{"heading_level":"`Subsection","heading_label_explicit":"false"},{"`Label":[{"`Page":["None","f.ml"]},""]},[{"`Link":["foo",[]]}]]}],"warnings":[]}
 --- input ---
+{{:https://github.com/ocaml/\
+   odoc/\
+issues/\
+                865\  }this issue}
+--- output ---
+{"value":[{"`Paragraph":[{"`Link":["https://github.com/ocaml/odoc/issues/865\\",[{"`Word":"this"},"`Space",{"`Word":"issue"}]]}]}],"warnings":["File \"f.ml.mld\":\nPages (.mld files) should start with a heading."]}
+--- input ---
 {2 {!foo}}
 --- output ---
 {"value":[{"`Heading":[{"heading_level":"`Subsection","heading_label_explicit":"false"},{"`Label":[{"`Page":["None","f.ml"]},""]},[{"`Reference":[{"`Root":["foo","`TUnknown"]},[]]}]]}],"warnings":[]}

test/model/semantics/odoc_semantic_test.ml

@@ -264,6 +264,13 @@ let heading () =
 
     let link_in_markup = test "{2 {{:foo}}}"
 
+    let multilines_link_in_markup =
+      test
+        {|{{:https://github.com/ocaml/\
+   odoc/\
+issues/\
+                865\  }this issue}|}
+
     let reference_in_markup = test "{2 {!foo}}"
 
     let two = test "{2 Foo}\n{2 Bar}"