Feature request: distinction between doc and non-doc comments

[neunenak]

It would be handy if I could write a justfile like:

# Do the thing
## Doing the thing is important for reason X - but make sure *not* do to the thing in circumstance Y, then you want
## to do other-thing Z.
do-thing arg1 arg2:
    do-some-stuff

And have this show up in just --list as:

do-thing arg1 arg2 # Do the thing

without printing the more detailed comments that begin with a double-#.

[neunenak]

This isn't something I care about, but it might also be useful to be able to write:

## Some comment
recipe:
    do-things

And allow the double-# to suppress "Some comment" when doing just --list.

[casey]

This seems useful, but the syntax might be confusing. In a lot of languages, doc comments use doubled comment markers, so doing the opposite seems a little weird. The other way might be better:

## Do the thing
# Doing the thing is important for reason X - but make sure *not* do to the thing in circumstance Y, then you want
# to do other-thing Z.
do-thing arg1 arg2:
    do-some-stuff

[neunenak]

I'm not wedded to ## as the syntax choice for suppressing printing document strings. I actually like explicitly adopting the ## convention for doc comments, but that'd be a major breaking change, right? Every just user would have to add an extra # or they'd suddenly stop seeing documentation comments they expect to appear no longer appear (maybe this could be an edition 2 thing?)

[casey]

I'm not wedded to ## as the syntax choice for suppressing printing document strings. I actually like explicitly adopting the ## convention for doc comments, but that'd be a major breaking change, right? Every just user would have to add an extra # or they'd suddenly stop seeing documentation comments they expect to appear no longer appear (maybe this could be an edition 2 thing?)

That's right, it'd be a breaking change. We'd want to make sure that it was really worth it, but it could first be introduced as an opt-in setting that defaults to false, and then later add an edition that makes that setting default to true.

[miguno]

+1 to this feature request.

FWIW, I also tried using ## intuitively to suppress the stdout-printing of a comment in a justfile. :-) (But I don't mind which syntax would finally be used for this purpose.)

[neunenak]

#2050 basically solves this . It might still be a good idea to introduce new comment syntax to distinguish doc and non-doc comments in a new just edition (#1201), but for now this issue can be closed.