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.
dnaka91 · Dec 21, 2023 · 160fbcd · 160fbcd
1 parent b72ba33
commit 160fbcd
Show file tree

Hide file tree

Showing 19 changed files with 53 additions and 32 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -51,41 +51,47 @@ 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>
       <td class="pr-8">
         <a class="text-lg name-const" href="constant.BOOL_FALSE.html">BOOL_FALSE</a>
       </td>
       <td>
+
       </td>
     </tr>
     <tr>
       <td class="pr-8">
         <a class="text-lg name-const" href="constant.INT.html">INT</a>
       </td>
       <td>
+
       </td>
     </tr>
     <tr>
       <td class="pr-8">
         <a class="text-lg name-const" href="constant.FLOAT.html">FLOAT</a>
       </td>
       <td>
+
       </td>
     </tr>
     <tr>
       <td class="pr-8">
         <a class="text-lg name-const" href="constant.STRING.html">STRING</a>
       </td>
       <td>
+
       </td>
     </tr>
     <tr>
       <td class="pr-8">
         <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
@@ -51,27 +51,31 @@ 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>
       <td class="pr-8">
         <a class="text-lg name-const" href="constant.NEWLINE_ESCAPE.html">NEWLINE_ESCAPE</a>
       </td>
       <td>
+
       </td>
     </tr>
     <tr>
       <td class="pr-8">
         <a class="text-lg name-const" href="constant.ESCAPES.html">ESCAPES</a>
       </td>
       <td>
+
       </td>
     </tr>
     <tr>
       <td class="pr-8">
         <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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -36,13 +36,15 @@ 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>
       <td class="pr-8">
         <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
@@ -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
@@ -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
@@ -36,13 +36,15 @@ 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>
       <td class="pr-8">
         <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>