From 160fbcdaa0c006be397fb2a72706813b71129c74 Mon Sep 17 00:00:00 2001
From: Dominik Nakamura <dnaka91@gmail.com>
Date: Thu, 21 Dec 2023 23:07:28 +0900
Subject: [PATCH] fix(doc): collect overview docs until the first empty line

In Markdown, a line break is only inserted if there is at least one
empty line between paragraphs. Therefore, collect all lines until the
first empty line is found, instead of simply taking the first line only.

This fixes potential cut-off of the overview item docs.
---
 crates/stef-doc/src/templates.rs              | 13 +++++++++++-
 crates/stef-doc/templates/detail/module.html  | 20 +++++--------------
 crates/stef-doc/templates/index.html          | 20 +++++--------------
 .../render__render@attribute_multi.stef.snap  |  1 +
 .../render__render@attribute_single.stef.snap |  1 +
 .../render__render@attribute_unit.stef.snap   |  1 +
 .../render__render@attributes.stef.snap       |  1 +
 ...render__render@attributes_min_ws.stef.snap |  1 +
 .../render__render@const_basic.stef.snap      |  6 ++++++
 .../render__render@const_string.stef.snap     |  4 ++++
 .../render__render@enum_min_ws.stef.snap      |  1 +
 .../snapshots/render__render@mixed.stef.snap  |  4 +++-
 .../render__render@module_basic.stef.snap     |  3 +++
 .../render__render@struct_min_ws.stef.snap    |  1 +
 .../render__render@types_basic.stef.snap      |  1 +
 .../render__render@types_generic.stef.snap    |  2 ++
 .../render__render@types_nested.stef.snap     |  1 +
 .../render__render@types_non_zero.stef.snap   |  1 +
 .../render__render@types_ref.stef.snap        |  3 +++
 19 files changed, 53 insertions(+), 32 deletions(-)

diff --git a/crates/stef-doc/src/templates.rs b/crates/stef-doc/src/templates.rs
index 8d8e622..57650d1 100644
--- a/crates/stef-doc/src/templates.rs
+++ b/crates/stef-doc/src/templates.rs
@@ -74,8 +74,19 @@ impl Display for PathUp {
     }
 }
 
+fn first_comment(item: &Comment<'_>) -> String {
+    item.0
+        .iter()
+        .take_while(|line| !line.value.trim().is_empty())
+        .fold(String::new(), |mut acc, line| {
+            acc.push_str(line.value);
+            acc.push('\n');
+            acc
+        })
+}
+
 fn merge_comments(item: &Comment<'_>) -> String {
-    item.0.iter().fold(String::new(),|mut acc, line| {
+    item.0.iter().fold(String::new(), |mut acc, line| {
         acc.push_str(line.value);
         acc.push('\n');
         acc
diff --git a/crates/stef-doc/templates/detail/module.html b/crates/stef-doc/templates/detail/module.html
index 325c39c..8e83468 100644
--- a/crates/stef-doc/templates/detail/module.html
+++ b/crates/stef-doc/templates/detail/module.html
@@ -26,9 +26,7 @@ <h3>Modules</h3>
         <a class="text-lg name-module" href="{{ m.name }}/index.html">{{ m.name }}</a>
       </td>
       <td>
-        {%- if !m.comment.0.is_empty() %}
-        {{ m.comment.0[0].value|markdown|trim|safe }}
-        {%- endif %}
+        {{ self::first_comment(m.comment)|markdown|trim|safe }}
       </td>
     </tr>
     {%- else %}
@@ -47,9 +45,7 @@ <h3>Structs</h3>
         <a class="text-lg name-struct" href="struct.{{ s.name }}.html">{{ s.name }}</a>
       </td>
       <td>
-        {%- if !s.comment.0.is_empty() %}
-        {{ s.comment.0[0].value|markdown|trim|safe }}
-        {%- endif %}
+        {{ self::first_comment(s.comment)|markdown|trim|safe }}
       </td>
     </tr>
     {%- else %}
@@ -68,9 +64,7 @@ <h3>Enums</h3>
         <a class="text-lg name-enum" href="enum.{{ e.name }}.html">{{ e.name }}</a>
       </td>
       <td>
-        {%- if !e.comment.0.is_empty() %}
-        {{ e.comment.0[0].value|markdown|trim|safe }}
-        {%- endif %}
+        {{ self::first_comment(e.comment)|markdown|trim|safe }}
       </td>
     </tr>
     {%- else %}
@@ -89,9 +83,7 @@ <h3>Aliases</h3>
         <a class="text-lg name-alias" href="alias.{{ a.name }}.html">{{ a.name }}</a>
       </td>
       <td>
-        {%- if !a.comment.0.is_empty() %}
-        {{ a.comment.0[0].value|markdown|trim|safe }}
-        {%- endif %}
+        {{ self::first_comment(a.comment)|markdown|trim|safe }}
       </td>
     </tr>
     {%- else %}
@@ -110,9 +102,7 @@ <h3>Constants</h3>
         <a class="text-lg name-const" href="constant.{{ c.name }}.html">{{ c.name }}</a>
       </td>
       <td>
-        {%- if !c.comment.0.is_empty() %}
-        {{ c.comment.0[0].value|markdown|trim|safe }}
-        {%- endif %}
+        {{ self::first_comment(c.comment)|markdown|trim|safe }}
       </td>
     </tr>
     {%- else %}
diff --git a/crates/stef-doc/templates/index.html b/crates/stef-doc/templates/index.html
index 784671e..c708930 100644
--- a/crates/stef-doc/templates/index.html
+++ b/crates/stef-doc/templates/index.html
@@ -17,9 +17,7 @@ <h3>Modules</h3>
         <a class="text-lg name-module" href="{{ m.name }}/index.html">{{ m.name }}</a>
       </td>
       <td>
-        {%- if !m.comment.0.is_empty() %}
-        {{ m.comment.0[0].value|markdown|trim|safe }}
-        {%- endif %}
+        {{ self::first_comment(m.comment)|markdown|trim|safe }}
       </td>
     </tr>
     {%- else %}
@@ -38,9 +36,7 @@ <h3>Structs</h3>
         <a class="text-lg name-struct" href="struct.{{ s.name }}.html">{{ s.name }}</a>
       </td>
       <td>
-        {%- if !s.comment.0.is_empty() %}
-        {{ s.comment.0[0].value|markdown|trim|safe }}
-        {%- endif %}
+        {{ self::first_comment(s.comment)|markdown|trim|safe }}
       </td>
     </tr>
     {%- else %}
@@ -59,9 +55,7 @@ <h3>Enums</h3>
         <a class="text-lg name-enum" href="enum.{{ e.name }}.html">{{ e.name }}</a>
       </td>
       <td>
-        {%- if !e.comment.0.is_empty() %}
-        {{ e.comment.0[0].value|markdown|trim|safe }}
-        {%- endif %}
+        {{ self::first_comment(e.comment)|markdown|trim|safe }}
       </td>
     </tr>
     {%- else %}
@@ -80,9 +74,7 @@ <h3>Aliases</h3>
         <a class="text-lg name-alias" href="alias.{{ a.name }}.html">{{ a.name }}</a>
       </td>
       <td>
-        {%- if !a.comment.0.is_empty() %}
-        {{ a.comment.0[0].value|markdown|trim|safe }}
-        {%- endif %}
+        {{ self::first_comment(a.comment)|markdown|trim|safe }}
       </td>
     </tr>
     {%- else %}
@@ -101,9 +93,7 @@ <h3>Constants</h3>
         <a class="text-lg name-const" href="constant.{{ c.name }}.html">{{ c.name }}</a>
       </td>
       <td>
-        {%- if !c.comment.0.is_empty() %}
-        {{ c.comment.0[0].value|markdown|trim|safe }}
-        {%- endif %}
+        {{ self::first_comment(c.comment)|markdown|trim|safe }}
       </td>
     </tr>
     {%- else %}
diff --git a/crates/stef-doc/tests/snapshots/render__render@attribute_multi.stef.snap b/crates/stef-doc/tests/snapshots/render__render@attribute_multi.stef.snap
index 6f283fb..6f2f302 100644
--- a/crates/stef-doc/tests/snapshots/render__render@attribute_multi.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@attribute_multi.stef.snap
@@ -36,6 +36,7 @@ input_file: crates/stef-parser/tests/inputs/attribute_multi.stef
         <a class="text-lg name-struct" href="struct.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@attribute_single.stef.snap b/crates/stef-doc/tests/snapshots/render__render@attribute_single.stef.snap
index 78a2073..85e6bb1 100644
--- a/crates/stef-doc/tests/snapshots/render__render@attribute_single.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@attribute_single.stef.snap
@@ -36,6 +36,7 @@ input_file: crates/stef-parser/tests/inputs/attribute_single.stef
         <a class="text-lg name-struct" href="struct.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@attribute_unit.stef.snap b/crates/stef-doc/tests/snapshots/render__render@attribute_unit.stef.snap
index 5d1fc13..37d6a37 100644
--- a/crates/stef-doc/tests/snapshots/render__render@attribute_unit.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@attribute_unit.stef.snap
@@ -36,6 +36,7 @@ input_file: crates/stef-parser/tests/inputs/attribute_unit.stef
         <a class="text-lg name-struct" href="struct.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@attributes.stef.snap b/crates/stef-doc/tests/snapshots/render__render@attributes.stef.snap
index 3d11556..9579e5c 100644
--- a/crates/stef-doc/tests/snapshots/render__render@attributes.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@attributes.stef.snap
@@ -36,6 +36,7 @@ input_file: crates/stef-parser/tests/inputs/attributes.stef
         <a class="text-lg name-struct" href="struct.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@attributes_min_ws.stef.snap b/crates/stef-doc/tests/snapshots/render__render@attributes_min_ws.stef.snap
index e02ec5d..ed227de 100644
--- a/crates/stef-doc/tests/snapshots/render__render@attributes_min_ws.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@attributes_min_ws.stef.snap
@@ -36,6 +36,7 @@ input_file: crates/stef-parser/tests/inputs/attributes_min_ws.stef
         <a class="text-lg name-struct" href="struct.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@const_basic.stef.snap b/crates/stef-doc/tests/snapshots/render__render@const_basic.stef.snap
index c3870be..ca3b96a 100644
--- a/crates/stef-doc/tests/snapshots/render__render@const_basic.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@const_basic.stef.snap
@@ -51,6 +51,7 @@ input_file: crates/stef-parser/tests/inputs/const_basic.stef
         <a class="text-lg name-const" href="constant.BOOL_TRUE.html">BOOL_TRUE</a>
       </td>
       <td>
+        
       </td>
     </tr>
     <tr>
@@ -58,6 +59,7 @@ input_file: crates/stef-parser/tests/inputs/const_basic.stef
         <a class="text-lg name-const" href="constant.BOOL_FALSE.html">BOOL_FALSE</a>
       </td>
       <td>
+        
       </td>
     </tr>
     <tr>
@@ -65,6 +67,7 @@ input_file: crates/stef-parser/tests/inputs/const_basic.stef
         <a class="text-lg name-const" href="constant.INT.html">INT</a>
       </td>
       <td>
+        
       </td>
     </tr>
     <tr>
@@ -72,6 +75,7 @@ input_file: crates/stef-parser/tests/inputs/const_basic.stef
         <a class="text-lg name-const" href="constant.FLOAT.html">FLOAT</a>
       </td>
       <td>
+        
       </td>
     </tr>
     <tr>
@@ -79,6 +83,7 @@ input_file: crates/stef-parser/tests/inputs/const_basic.stef
         <a class="text-lg name-const" href="constant.STRING.html">STRING</a>
       </td>
       <td>
+        
       </td>
     </tr>
     <tr>
@@ -86,6 +91,7 @@ input_file: crates/stef-parser/tests/inputs/const_basic.stef
         <a class="text-lg name-const" href="constant.BYTES.html">BYTES</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@const_string.stef.snap b/crates/stef-doc/tests/snapshots/render__render@const_string.stef.snap
index 25ce6e5..3262316 100644
--- a/crates/stef-doc/tests/snapshots/render__render@const_string.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@const_string.stef.snap
@@ -51,6 +51,7 @@ input_file: crates/stef-parser/tests/inputs/const_string.stef
         <a class="text-lg name-const" href="constant.SIMPLE.html">SIMPLE</a>
       </td>
       <td>
+        
       </td>
     </tr>
     <tr>
@@ -58,6 +59,7 @@ input_file: crates/stef-parser/tests/inputs/const_string.stef
         <a class="text-lg name-const" href="constant.NEWLINE_ESCAPE.html">NEWLINE_ESCAPE</a>
       </td>
       <td>
+        
       </td>
     </tr>
     <tr>
@@ -65,6 +67,7 @@ input_file: crates/stef-parser/tests/inputs/const_string.stef
         <a class="text-lg name-const" href="constant.ESCAPES.html">ESCAPES</a>
       </td>
       <td>
+        
       </td>
     </tr>
     <tr>
@@ -72,6 +75,7 @@ input_file: crates/stef-parser/tests/inputs/const_string.stef
         <a class="text-lg name-const" href="constant.MULTILINE.html">MULTILINE</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@enum_min_ws.stef.snap b/crates/stef-doc/tests/snapshots/render__render@enum_min_ws.stef.snap
index 7ab8b82..5ff9888 100644
--- a/crates/stef-doc/tests/snapshots/render__render@enum_min_ws.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@enum_min_ws.stef.snap
@@ -41,6 +41,7 @@ input_file: crates/stef-parser/tests/inputs/enum_min_ws.stef
         <a class="text-lg name-enum" href="enum.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@mixed.stef.snap b/crates/stef-doc/tests/snapshots/render__render@mixed.stef.snap
index 95db2ef..e8a8329 100644
--- a/crates/stef-doc/tests/snapshots/render__render@mixed.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@mixed.stef.snap
@@ -60,6 +60,7 @@ input_file: crates/stef-parser/tests/inputs/mixed.stef
         <a class="text-lg name-struct" href="struct.Address.html">Address</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
@@ -671,7 +672,8 @@ const MAX_AGE: u8 = 120;</pre>
         <a class="text-lg name-const" href="constant.MAX_DAY.html">MAX_DAY</a>
       </td>
       <td>
-        <p>Absolute maximum for a day, but might be even less depending</p>
+        <p>Absolute maximum for a day, but might be even less depending
+on the month.</p>
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@module_basic.stef.snap b/crates/stef-doc/tests/snapshots/render__render@module_basic.stef.snap
index 755c060..253627a 100644
--- a/crates/stef-doc/tests/snapshots/render__render@module_basic.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@module_basic.stef.snap
@@ -31,6 +31,7 @@ input_file: crates/stef-parser/tests/inputs/module_basic.stef
         <a class="text-lg name-module" href="a/index.html">a</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
@@ -106,6 +107,7 @@ input_file: crates/stef-parser/tests/inputs/module_basic.stef
         <a class="text-lg name-struct" href="struct.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
@@ -173,6 +175,7 @@ input_file: crates/stef-parser/tests/inputs/module_basic.stef
         <a class="text-lg name-enum" href="enum.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@struct_min_ws.stef.snap b/crates/stef-doc/tests/snapshots/render__render@struct_min_ws.stef.snap
index ee832ac..e53af85 100644
--- a/crates/stef-doc/tests/snapshots/render__render@struct_min_ws.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@struct_min_ws.stef.snap
@@ -36,6 +36,7 @@ input_file: crates/stef-parser/tests/inputs/struct_min_ws.stef
         <a class="text-lg name-struct" href="struct.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@types_basic.stef.snap b/crates/stef-doc/tests/snapshots/render__render@types_basic.stef.snap
index 75789bc..6cfac0e 100644
--- a/crates/stef-doc/tests/snapshots/render__render@types_basic.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@types_basic.stef.snap
@@ -36,6 +36,7 @@ input_file: crates/stef-parser/tests/inputs/types_basic.stef
         <a class="text-lg name-struct" href="struct.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@types_generic.stef.snap b/crates/stef-doc/tests/snapshots/render__render@types_generic.stef.snap
index 2baf5b6..c5a35c3 100644
--- a/crates/stef-doc/tests/snapshots/render__render@types_generic.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@types_generic.stef.snap
@@ -36,6 +36,7 @@ input_file: crates/stef-parser/tests/inputs/types_generic.stef
         <a class="text-lg name-struct" href="struct.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
     <tr>
@@ -43,6 +44,7 @@ input_file: crates/stef-parser/tests/inputs/types_generic.stef
         <a class="text-lg name-struct" href="struct.SampleUnnamed.html">SampleUnnamed</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@types_nested.stef.snap b/crates/stef-doc/tests/snapshots/render__render@types_nested.stef.snap
index c3df923..e318034 100644
--- a/crates/stef-doc/tests/snapshots/render__render@types_nested.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@types_nested.stef.snap
@@ -36,6 +36,7 @@ input_file: crates/stef-parser/tests/inputs/types_nested.stef
         <a class="text-lg name-struct" href="struct.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@types_non_zero.stef.snap b/crates/stef-doc/tests/snapshots/render__render@types_non_zero.stef.snap
index 7fc31bb..c1a9286 100644
--- a/crates/stef-doc/tests/snapshots/render__render@types_non_zero.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@types_non_zero.stef.snap
@@ -36,6 +36,7 @@ input_file: crates/stef-parser/tests/inputs/types_non_zero.stef
         <a class="text-lg name-struct" href="struct.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
diff --git a/crates/stef-doc/tests/snapshots/render__render@types_ref.stef.snap b/crates/stef-doc/tests/snapshots/render__render@types_ref.stef.snap
index baff5af..60401bb 100644
--- a/crates/stef-doc/tests/snapshots/render__render@types_ref.stef.snap
+++ b/crates/stef-doc/tests/snapshots/render__render@types_ref.stef.snap
@@ -36,6 +36,7 @@ input_file: crates/stef-parser/tests/inputs/types_ref.stef
         <a class="text-lg name-struct" href="struct.Sample.html">Sample</a>
       </td>
       <td>
+        
       </td>
     </tr>
     <tr>
@@ -43,6 +44,7 @@ input_file: crates/stef-parser/tests/inputs/types_ref.stef
         <a class="text-lg name-struct" href="struct.KeyValue.html">KeyValue</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>
@@ -55,6 +57,7 @@ input_file: crates/stef-parser/tests/inputs/types_ref.stef
         <a class="text-lg name-enum" href="enum.Test123.html">Test123</a>
       </td>
       <td>
+        
       </td>
     </tr>
   </table>