Add more exhaustive tests for docstring markdown conversion

ocaml · May 8, 2023 · 60c2166 · 60c2166
1 parent 67d6b9b
commit 60c2166
Show file tree

Hide file tree

Showing 2 changed files with 127 additions and 26 deletions.
diff --git a/ocaml-lsp-server/src/doc_to_md.ml b/ocaml-lsp-server/src/doc_to_md.ml
@@ -3,8 +3,15 @@ open Cmarkit
 
 (** TODO:
 
-    - Support meta from odoc-parser locations
-    - Add support for references *)
+    - Add support for references
+    - Broken lists
+    - Labels in headers
+    - Align text with HTML
+    - Verbatim is indented in tests
+
+    Unsupported (next):
+
+    - Support meta from odoc-parser locations *)
 
 type t =
   | Raw of string
@@ -278,19 +285,8 @@ and block_element_list_to_block l =
 let translate doc : t =
   let location = Lexing.dummy_pos in
   let v = Odoc_parser.parse_comment ~location ~text:doc in
-  match Odoc_parser.warnings v with
-  | [] ->
-    let ast = Odoc_parser.ast v in
-    let block = block_element_list_to_block ast in
-    let doc = Doc.make block in
-    let cmark = Cmarkit_commonmark.of_doc doc in
-    Markdown cmark
-  | warnings ->
-    let messages =
-      List.map
-        ~f:(fun warn -> ("msg", `String (Odoc_parser.Warning.to_string warn)))
-        warnings
-    in
-    Log.log ~section:"debug" (fun () ->
-        Log.msg "Invalid documentation comment" messages);
-    Raw doc
+  let ast = Odoc_parser.ast v in
+  let block = block_element_list_to_block ast in
+  let doc = Doc.make block in
+  let cmark = Cmarkit_commonmark.of_doc doc in
+  Markdown cmark
diff --git a/ocaml-lsp-server/test/e2e/__tests__/textDocument-signatureHelp.ts b/ocaml-lsp-server/test/e2e/__tests__/textDocument-signatureHelp.ts
@@ -244,10 +244,59 @@ describe_opt("textDocument/completion", () => {
   it("can return documentation for the function being applied", async () => {
     openDocument(
       outdent`
-      (** This function has a nice documentation.
-
-          It performs division of two integer numbers.
-
+      (** This is an example of a docstring that demonstrates various ocamldoc syntax features.
+
+          {3 Sections and Labels}
+      
+          We can create sections using {3 Section title} and labels using {3:label_name Section title with label}
+      
+          {3 Links and Cross-references}
+      
+          External links: {{:https://ocaml.org/} OCaml's official website}
+      
+          {3 Inline Formatting}
+      
+          {b Bold}, {i Italic}, {e Emphasize}, {^ Superscript}, {_ Subscript}, and [inline code]
+      
+          {3 Text Alignment}
+      
+          {C Centered text}
+          {L Left-aligned text}
+          {R Right-aligned text}
+      
+          {3 Lists}
+      
+          {ol
+          {- Ordered list item 1}
+          {- Ordered list item 2}
+          }
+      
+          {ul
+          {- Unordered list item 1}
+          {- Unordered list item 2}
+          }
+
+          - Unordered list item 1
+          - Unordered list item 2
+
+          {3 Code Blocks}
+      
+          {[
+            let square x = x * x
+            let result = square 3
+          ]}
+      
+          {3 Verbatim}
+      
+          {v
+          This text will be displayed verbatim.
+          No formatting will be applied.
+          v}
+            
+          {3 Module List}
+      
+          {!modules: Array List String}
+        
           @param x dividend
           @param divisor
 
@@ -288,10 +337,66 @@ describe_opt("textDocument/completion", () => {
           ],
           documentation: {
             kind: "markdown",
-            value: outdent`
-              This function has a nice documentation.
-
-              It performs division of two integer numbers.
+            value: outdent`This is an example of a docstring that demonstrates various ocamldoc syntax features.
+              
+              ### Sections and Labels
+              
+              We can create sections using 
+              
+              ### Section title
+              
+              and labels using 
+              
+              ### Section title with label
+              
+              ### Links and Cross-references
+              
+              External links: [OCaml's official website](https://ocaml.org/)
+              
+              ### Inline Formatting
+              
+              **Bold**, *Italic*, *Emphasize*, Superscript, Subscript, and \`inline code\`
+              
+              ### Text Alignment
+          
+              Centered text
+              
+              Left-aligned text
+              
+              Right-aligned text
+              
+              ### Lists
+              
+              1.Ordered list item 1
+              2.Ordered list item 2
+          
+              *Unordered list item 1
+              *Unordered list item 2
+
+              *Unordered list item 1
+              *Unordered list item 2
+              
+              ### Code Blocks
+              
+              \`\`\`
+              let square x = x * x
+              let result = square 3
+              let result = square 3
+              \`\`\`
+              
+              ### Verbatim
+              
+              \`\`\`verb
+                  This text will be displayed verbatim.
+                  No formatting will be applied.
+                  No formatting will be applied.
+              \`\`\`
+              
+              ### Module List
+              
+              *Array
+              *List
+              *String
 
               ***@param*** \`x\`
               dividend