From 2bacbddadb781600f3b7b7a1c202c66c3ae6df3c Mon Sep 17 00:00:00 2001
From: Casey Rodarmor <casey@rodarmor.com>
Date: Sat, 25 May 2024 18:12:55 -0700
Subject: [PATCH] Print multi-line doc comments before recipe in `--list`
 (#2090)

---
 src/subcommand.rs   | 41 ++++++++++++++++++++++++++++-------------
 tests/attributes.rs | 32 +++++++++++++++++++++++++++-----
 2 files changed, 55 insertions(+), 18 deletions(-)

diff --git a/src/subcommand.rs b/src/subcommand.rs
index f7733fc..5e7b7d2 100644
--- a/src/subcommand.rs
+++ b/src/subcommand.rs
@@ -566,26 +566,41 @@ impl Subcommand {
           .chain(aliases.get(recipe.name()).unwrap_or(&Vec::new()))
           .enumerate()
         {
-          print!(
-            "{}{}",
-            config.list_prefix.repeat(level + 1),
-            RecipeSignature { name, recipe }.color_display(config.color.stdout())
-          );
-
           let doc = if i == 0 {
             recipe.doc().map(Cow::Borrowed)
           } else {
             Some(Cow::Owned(format!("alias for `{}`", recipe.name)))
           };
 
+          if let Some(doc) = &doc {
+            if doc.lines().count() > 1 {
+              for line in doc.lines() {
+                println!(
+                  "{}{} {}",
+                  config.list_prefix.repeat(level + 1),
+                  config.color.stdout().doc().paint("#"),
+                  config.color.stdout().doc().paint(line),
+                );
+              }
+            }
+          }
+
+          print!(
+            "{}{}",
+            config.list_prefix.repeat(level + 1),
+            RecipeSignature { name, recipe }.color_display(config.color.stdout())
+          );
+
           if let Some(doc) = doc {
-            print!(
-              "{:padding$}{} {}",
-              "",
-              config.color.stdout().doc().paint("#"),
-              config.color.stdout().doc().paint(&doc),
-              padding = max_signature_width.saturating_sub(signature_widths[name]) + 1,
-            );
+            if doc.lines().count() <= 1 {
+              print!(
+                "{:padding$}{} {}",
+                "",
+                config.color.stdout().doc().paint("#"),
+                config.color.stdout().doc().paint(&doc),
+                padding = max_signature_width.saturating_sub(signature_widths[name]) + 1,
+              );
+            }
           }
           println!();
         }
diff --git a/tests/attributes.rs b/tests/attributes.rs
index d527b0e..9c79bb7 100644
--- a/tests/attributes.rs
+++ b/tests/attributes.rs
@@ -156,11 +156,11 @@ fn doc_attribute_suppress() {
   Test::new()
     .justfile(
       "
-    # Non-document comment
-    [doc]
-    foo:
-      echo foo
-  ",
+        # Non-document comment
+        [doc]
+        foo:
+          echo foo
+      ",
     )
     .args(["--list"])
     .stdout(
@@ -171,3 +171,25 @@ fn doc_attribute_suppress() {
     )
     .run();
 }
+
+#[test]
+fn doc_multiline() {
+  Test::new()
+    .justfile(
+      "
+        [doc('multiline
+        comment')]
+        foo:
+      ",
+    )
+    .args(["--list"])
+    .stdout(
+      "
+    Available recipes:
+        # multiline
+        # comment
+        foo
+        ",
+    )
+    .run();
+}