Doc attribute and test

src/attribute.rs

@@ -5,6 +5,9 @@ use super::*;
 #[serde(rename_all = "kebab-case")]
 pub(crate) enum Attribute<'src> {
   Confirm(Option<StringLiteral<'src>>),
+  Doc {
+    docstring: Option<String>,
+  },
   #[strum(disabled)]
   Group {
     name: StringLiteral<'src>,
@@ -27,6 +30,9 @@ impl<'src> Attribute<'src> {
     let name_str = name.lexeme();
 
     Ok(match (name_str, maybe_argument) {
+      ("doc", arg) => Self::Doc {
+        docstring: arg.map(|arg| arg.cooked.clone()),
+      },
       ("group", Some(name)) => Self::Group { name },
       ("group", None) => {
         return Err(name.error(CompileErrorKind::MissingAttributeArgument {

src/list_recipes.rs

@@ -76,7 +76,7 @@ fn print_recipe(
 
     let padding =
       max_line_width.saturating_sub(line_widths.get(name).copied().unwrap_or(max_line_width));
-    match (i, recipe.doc) {
+    match (i, recipe.docstring()) {
       (0, Some(doc)) => print_doc_comment(doc, padding, doc_color),
       (0, None) => (),
       _ => {

src/recipe.rs

@@ -439,6 +439,15 @@ impl<'src, D> Recipe<'src, D> {
     }
     groups
   }
+
+  pub(crate) fn docstring(&self) -> Option<&str> {
+    for attribute in &self.attributes {
+      if let Attribute::Doc { docstring } = attribute {
+        return docstring.as_ref().map(|s| s.as_str());
+      }
+    }
+    self.doc
+  }
 }
 
 impl<'src, D: Display> ColorDisplay for Recipe<'src, D> {

tests/attributes.rs

@@ -129,3 +129,33 @@ fn unexpected_attribute_argument() {
     .status(1)
     .run();
 }
+
+test! {
+  name: doc_attribute,
+  justfile: "
+    # Non-document comment
+    [doc('The real docstring')]
+    foo:
+      echo foo
+  ",
+  args: ("--list"),
+  stdout: "
+    Available recipes:
+        foo # The real docstring
+  ",
+}
+
+test! {
+  name: suppress_doc_comment,
+  justfile: "
+    # Non-document comment
+    [doc]
+    foo:
+      echo foo
+  ",
+  args: ("--list"),
+  stdout: "
+    Available recipes:
+        foo
+  ",
+}