Print mutli-line doc comments before recipe

[casey]

No description provided.

[casey]

@kranurag7 re your comment in #2090, this prints out multiline doc comments:

[doc('multiline
comment')]
foo:

Like this:

Available recipes:
    # multiline
    # comment
    foo

How does that strike you?

I was thinking that:

Available recipes:
    foo # multiline
          comment

Could get awkward to read, and would mean that a long doc comment would be squashed to the right.

[kranurag7]

Thanks for the fix.

With 1st, one have to re-think that the comment is for the recipe that is listed down and one may get confused if the comment is for the recipe listed down or above.

I think keeping it on the right is more flexible for users because then they'll read from left to right.

Details

$ ./target/debug/just -f justfile.foo --list
Available recipes:
    # multiline
    # comment
    foo
    hello
    moo
    # this is a comment
    # for test recipe
    # comment
    test
    work
    zoo

Could get awkward to read, and would mean that a long doc comment would be squashed to the right.

we can auto-wrap after few characters, something like git commit messages where auto-wrapping is recommended after 72 characters.

[casey]

Auto-wrapping would require word-splitting, which is error prone. For example, if word-splitting is done on spaces, the splitter would split commands like echo foo in the middle. Whatever we do, I'm inclined to leave the lines as the author wrote them, and they can adjust the line-length how they want.

[casey]

I'm going to merge this, since it's definitely an improvement over the current behavior. I'm still undecided about trying to print multi-line doc-comments after recipes with alignment. I think it's probably not a simple win, since I think things like this look pretty awkward:

Available recipes:
    a # this is
        a long comment
    b # another comment
```

[zekefast]

I'm going to merge this, since it's definitely an improvement over the current behavior. I'm still undecided about trying to print multi-line doc-comments after recipes with alignment. I think it's probably not a simple win, since I think things like this look pretty awkward:

Please, please do the alignment! We have lots of recipes with a lot of docs and the output of just --list is just a mess.

It wasn't well aligned previously, especially when there is a recipe with long list of arguments (3 and more), but with moving documentation under the recipe name while for other recipes it is right aligned make everything very hard to read!

[casey]

@zekefast I'm happy to consider it! Could you open a new issue with an example of the current output you're getting how you'd like it to be improved?