Doc attribute

src/attribute.rs

@@ -10,6 +10,9 @@ use super::*;
 #[strum_discriminants(strum(serialize_all = "kebab-case"))]
 pub(crate) enum Attribute<'src> {
   Confirm(Option<StringLiteral<'src>>),
+  Doc {
+    docstring: Option<StringLiteral<'src>>,
+  },
   Group(StringLiteral<'src>),
   Linux,
   Macos,
@@ -24,7 +27,7 @@ pub(crate) enum Attribute<'src> {
 impl AttributeDiscriminant {
   fn argument_range(self) -> RangeInclusive<usize> {
     match self {
-      Self::Confirm => 0..=1,
+      Self::Confirm | Self::Doc => 0..=1,
       Self::Group => 1..=1,
       Self::Linux
       | Self::Macos
@@ -72,6 +75,9 @@ impl<'src> Attribute<'src> {
 
     Ok(match discriminant {
       Confirm => Self::Confirm(argument),
+      Doc => Self::Doc {
+        docstring: argument,
+      },
       Group => Self::Group(argument.unwrap()),
       Linux => Self::Linux,
       Macos => Self::Macos,
@@ -91,6 +97,7 @@ impl<'src> Attribute<'src> {
   fn argument(&self) -> Option<&StringLiteral> {
     match self {
       Self::Confirm(prompt) => prompt.as_ref(),
+      Self::Doc { docstring } => docstring.as_ref(),
       Self::Group(name) => Some(name),
       Self::Linux
       | Self::Macos
@@ -107,7 +114,6 @@ impl<'src> Attribute<'src> {
 impl<'src> Display for Attribute<'src> {
   fn fmt(&self, f: &mut Formatter) -> Result<(), fmt::Error> {
     write!(f, "{}", self.name())?;
-
     if let Some(argument) = self.argument() {
       write!(f, "({argument})")?;
     }

src/recipe.rs

@@ -450,6 +450,15 @@ impl<'src, D> Recipe<'src, D> {
       })
       .collect()
   }
+
+  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.cooked.as_ref());
+      }
+    }
+    self.doc
+  }
 }
 
 impl<'src, D: Display> ColorDisplay for Recipe<'src, D> {

src/subcommand.rs

@@ -573,7 +573,7 @@ impl Subcommand {
           );
 
           let doc = if i == 0 {
-            recipe.doc.map(Cow::Borrowed)
+            recipe.docstring().map(Cow::Borrowed)
           } else {
             Some(Cow::Owned(format!("alias for `{}`", recipe.name)))
           };

tests/attributes.rs

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