Differentiate documentation and non-documentation comment syntax

[casey]

Consider giving documentation comments a dedicated syntax. The syntax that I currently favor is ## for doc-comments.

Pros:

• Prevent comments that aren't intended as doc-comments from being picked up in recipe descriptions.
• Make it possible to write comments about recipes that aren't doc comments.
• Allow users to write multi-line doc-comments but only use the first line in --list output. (See below for an example.)
• Can emit an error if doc-comments aren't used correctly.
• Slightly simplify the parser.

Cons:

• Users would have to change existing doc-comments to use the new syntax.
• If using a doc-comment where none is expected is an error, then this will be a breaking change. The more pre-existing use of the new doc-comment syntax there is (e.g. for styling purposes), the more disruptive this change will be. ## is used by around 1% of justfiles that I've scraped from GitHub. (This doesn't count ###, since we can ignore comments that start with ### to make it a less disruptive change.) Options like #: would be less disruptive, but weirder.

If I did this, I would first make Just strip additional #s from existing doc-comments. This would make it so there would be a period where # and ## comments would work, to make the change less disruptive. (If this wasn't done, then you would see build # # description if you tried to use ## doc-comments.)

I'm still on the fence about this change. I think it would be nice, and if I was writing Just from scratch I would certainly do it from the beginning. However, I'm unsure if it's worth it, given that there are many Justfiles out there.

This could be given a phased roll-out:

1. Make it so ## comments work without an additional # appearing in --list output
2. Warn if a # comment is picked up as a doc-comment
3. Stop showing # as doc-comments

Multi-line doc-comment example

## Build the project
## More detail about what this command does.
build:
  ./build

$ just --list
Available recipes:
    build # Build the project

[runeimp]

Good idea. But I'm not a fan of usurping shebang syntax for it. For those who are not yet or just getting familiar with the concepts of shebangs and their usage this could be very confusing. The following feel better in my mind.

#: doc comment which might align with the new `:=` assignment syntax well

#$ doc comment which stands out

## doc comment which is easy to write but could be misunderstood as user styling
###
Fenced doc comment? Would go nicely with the ## doc comment style.
###

[casey]

Although it might be mistaken for user styling, I think out of those I like ## the best. It's easy to type, it's similar to doc comments in other languages (in the sense that doc comment syntax is often normal syntax with one character duplicated, and it's used by at least one other language.

[dionjwa]

This would be great to support #553. Being able to say in a doc string "I'm going to build X and put it in location (configurable via e.g. .env) Y" would add so much power to concise documentation.

[casey]

@dionjwa Great point! Adding dedicated doc-comment syntax would allow for introducing new features.

[casey]

I think that using ## would be very disruptive, just given the proportion of justfiles that use ## for styling, so I think ## is out.

[dionjwa]

What about @# for "hidden" documentation? This matches the existing way I add comments I don't want automatically printed out:

command:
    @# a comment that is NOT echo'd to stdout
    # This comment is echo'd to stdout
    ls

Actually, now that I write this, I would favour that # should be hidden comments, and @# should be explicit command doc strings. Writing internal comments should have smallest writing overhead, whereas command doc strings are more "special".

This would be a breaking change, but worth it for such a useful feature.

[casey]

There is now a [doc] attribute which can be used to give recipes multi-line doc comments, or used with no argument to prevent a leading comment from being used as the recipe's doc comment.