fix(cairodoc): handle paragraphs properly (#7063)

crates/cairo-lang-doc/src/db.rs

@@ -430,35 +430,31 @@ fn join_lines_of_comments(lines: &Vec<String>) -> String {
             (line.starts_with("    ") || line.starts_with("\t")) && !in_code_block;
         let contains_delimiter = trimmed_line.starts_with("```") || is_indented_code_line;
 
-        if is_indented_code_line && !in_code_block {
-            // We are at the start of an indented code block, add an extra newline
-            result.push('\n');
-        }
-
         if contains_delimiter {
             // If we stumble upon the opening of a code block, we have to make a newline.
-            if !in_code_block {
+            if !in_code_block && !result.ends_with('\n') {
                 result.push('\n');
             }
             in_code_block = !in_code_block;
 
             result.push_str(line);
             result.push('\n');
-
-            // If we just closed an indented code block, add an extra newline.
-            if !in_code_block && is_indented_code_line {
-                result.push('\n');
-            }
-
             continue;
         }
 
         if in_code_block {
             result.push_str(line);
             result.push('\n');
         } else {
-            result.push_str(line);
-            result.push(' ');
+            // Outside code blocks, handle paragraph breaks identified by empty lines.
+            if trimmed_line.is_empty() {
+                result.push_str("\n\n");
+            } else {
+                if !result.is_empty() && !result.ends_with("\n\n") && !result.ends_with('\n') {
+                    result.push(' ');
+                }
+                result.push_str(trimmed_line);
+            }
         }
     }
     result.trim_end().to_string()

crates/cairo-lang-doc/src/tests/test-data/basic.txt

@@ -205,7 +205,7 @@ struct Point {
 }
 
 //! > Item documentation #9
-Point struct representing a point in a 2d space. Example usage: 
+Point struct representing a point in a 2d space. Example usage:
 ```cairo
   fn new_Point() {
     Point {x: 12, y: 14}
@@ -278,7 +278,7 @@ Content("No answer variant.")
 struct Circle {}
 
 //! > Item documentation #15
-Example usage: 
+Example usage:
 ```cairo
   fn new_circle() {
     // [Circle] <- this should not tokenize as a link (neither be resolved), we're inside code
@@ -296,7 +296,7 @@ Content("```")
 struct Square {}
 
 //! > Item documentation #16
-Below there is a code example  
+Below there is a code example
 
     First line of code
     // Comment inside the code block, that should be ignored. [Square] <- it will be ignored as

crates/cairo-lang-doc/src/tests/test-data/comment_markers.txt

@@ -32,24 +32,6 @@ trait T {
     ) -> Option<U>;
 }
 
-//! > expected_item_0
-Maps an `Option<T>` to `Option<U>` by applying a function to a contained value (if `Some`) or returns `Option::None` (if `None`).
-
-# Examples
-
-```
-let maybe_some_string: Option<ByteArray> = Option::Some("Hello, World!");
-// `Option::map` takes self *by value*, consuming `maybe_some_string`
-let maybe_some_len = maybe_some_string.map(|s: ByteArray| s.len());
-assert!(maybe_some_len == Option::Some(13));
-
-let x: Option<ByteArray> = Option::None;
-assert!(x.map(|s: ByteArray| s.len()) == Option::None);
-```
-
-//! > expected_signature_0
-fn map<U, F, +Destruct<F>, +core::ops::FnOnce<F, (T,)>[Output: U]>(self: Option<T>, f: F) -> Option<U>
-
 //! > Item signature #1
 
 //! > Item documentation #1
@@ -69,7 +51,10 @@ fn map<U, F, +Destruct<F>, +core::ops::FnOnce<F, (T,)>[Output: U]>(
 ) -> Option<U>
 
 //! > Item documentation #3
-Maps an `Option<T>` to `Option<U>` by applying a function to a contained value (if `Some`) or returns `Option::None` (if `None`).  # Examples  
+Maps an `Option<T>` to `Option<U>` by applying a function to a contained value (if `Some`) or returns `Option::None` (if `None`).
+
+# Examples
+
 ```cairo
 let maybe_some_string: Option<ByteArray> = Option::Some("Hello, World!");
 // `Option::map` takes self *by value*, consuming `maybe_some_string`
@@ -91,7 +76,8 @@ Content(") or returns ")
 Content("`Option::None`")
 Content(" (if ")
 Content("`None`")
-Content(").  # Examples")
+Content(").")
+Content("Examples")
 Content("\n```cairo\n")
 Content("let maybe_some_string: Option<ByteArray> = Option::Some(\"Hello, World!\");\n// `Option::map` takes self *by value*, consuming `maybe_some_string`\nlet maybe_some_len = maybe_some_string.map(|s: ByteArray| s.len());\nassert!(maybe_some_len == Option::Some(13));\n\nlet x: Option<ByteArray> = Option::None;\nassert!(x.map(|s: ByteArray| s.len()) == Option::None);\n")
 Content("```")

crates/cairo-lang-doc/src/tests/test-data/submodule.txt

@@ -52,7 +52,7 @@ mod inner_sub_module {
 //! > Item signature #1
 
 //! > Item documentation #1
-This is a testing crate file. It's for the tests purposes only. 
+This is a testing crate file. It's for the tests purposes only.
 ```cairo
   let a = 5;
 ```
@@ -68,7 +68,7 @@ Content("This is also testing crate. After the code example. We don't take respo
 //! > Item signature #2
 
 //! > Item documentation #2
-This is a submodule regarding the module_level_comments. It's used to make sure crate / module level comments are parsed in a correct way. Testing purposes only! This one is just a prefix comment for a module. 
+This is a submodule regarding the module_level_comments. It's used to make sure crate / module level comments are parsed in a correct way. Testing purposes only! This one is just a prefix comment for a module.
 ```rust
   let a = String::from("This also works fine");
 ```
@@ -106,7 +106,7 @@ Content("Hello function inside the inner module.")
 fn main()
 
 //! > Item documentation #5
-Main function. Uses [cairo_submodule_code::inner_sub_module]. Empty code example. 
+Main function. Uses [cairo_submodule_code::inner_sub_module]. Empty code example.
 ```rust
 ```