Add [doc] attribute to set and suppress documentation comments (#2050)

README.md

@@ -1079,6 +1079,27 @@ Available recipes:
     test # test stuff
 ```
 
+The `[doc]` attribute can be used to set or suppress a recipe's doc comment:
+
+```just
+# This comment won't appear
+[doc('Build stuff')]
+build:
+  ./bin/build
+
+# This one won't either
+[doc]
+test:
+  ./bin/test
+```
+
+```sh
+$ just --list
+Available recipes:
+    build # Build stuff
+    test
+```
+
 ### Variables and Substitution
 
 Variables, strings, concatenation, path joining, and substitution using `{{…}}`
@@ -1622,8 +1643,9 @@ Recipes may be annotated with attributes that change their behavior.
 | Name | Description |
 |------|-------------|
 | `[confirm]`<sup>1.17.0</sup> | Require confirmation prior to executing recipe. |
-| `[confirm('prompt')]`<sup>1.23.0</sup> | Require confirmation prior to executing recipe with a custom prompt. |
+| `[confirm('PROMPT')]`<sup>1.23.0</sup> | Require confirmation prior to executing recipe with a custom prompt. |
-| `[group('NAME"']`<sup>master</sup> | Put recipe in [recipe group](#recipe-groups) `NAME`.
+| `[doc('DOC')]`<sup>master</sup> | Set recipe's [documentation comment](#documentation-comments) to `DOC`. |
+| `[group('NAME"']`<sup>master</sup> | Put recipe in [recipe group](#recipe-groups) `NAME`. |
 | `[linux]`<sup>1.8.0</sup> | Enable recipe on Linux. |
 | `[macos]`<sup>1.8.0</sup> | Enable recipe on MacOS. |
 | `[no-cd]`<sup>1.9.0</sup> | Don't change directory before executing recipe. |

src/attribute.rs

@@ -10,6 +10,7 @@ use super::*;
 #[strum_discriminants(strum(serialize_all = "kebab-case"))]
 pub(crate) enum Attribute<'src> {
   Confirm(Option<StringLiteral<'src>>),
+  Doc(Option<StringLiteral<'src>>),
   Group(StringLiteral<'src>),
   Linux,
   Macos,
@@ -24,7 +25,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 +73,7 @@ impl<'src> Attribute<'src> {
 
     Ok(match discriminant {
       Confirm => Self::Confirm(argument),
+      Doc => Self::Doc(argument),
       Group => Self::Group(argument.unwrap()),
       Linux => Self::Linux,
       Macos => Self::Macos,
@@ -91,7 +93,8 @@ impl<'src> Attribute<'src> {
   fn argument(&self) -> Option<&StringLiteral> {
     match self {
       Self::Confirm(prompt) => prompt.as_ref(),
-      Self::Group(name) => Some(name),
+      Self::Doc(doc) => doc.as_ref(),
+      Self::Group(group) => Some(group),
       Self::Linux
       | Self::Macos
       | Self::NoCd
@@ -107,7 +110,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 doc(&self) -> Option<&str> {
+    for attribute in &self.attributes {
+      if let Attribute::Doc(doc) = attribute {
+        return doc.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.doc().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 doc_attribute_suppress() {
+  Test::new()
+    .justfile(
+      "
+    # Non-document comment
+    [doc]
+    foo:
+      echo foo
+  ",
+    )
+    .args(["--list"])
+    .stdout(
+      "
+    Available recipes:
+        foo
+        ",
+    )
+    .run();
+}