`just --list` support multi-line documentation comments
- Dominant language
- Rust
- Stars
- 35.8k
- Forks
- 846
- Avg merge
- 27m
- Merged PRs (30d)
- 3
Description
I think there are a few things that could make the list view more useful as a "usage" document for a given Justfile.
Currently, if we have a Justfile such as this:
```
# Cool summary of command functionality!
#
# Some extra warnings, longer documentation, and explanation
# of what this command does.
command:
echo "hello"
```
Then we run `just --list`, it prints the last line of the comment above the command, which is a bit inconvenient.
```
Available recipes:
command # of what this command does.
```
I think supporting multiline documentation would be valuable, where the default of `--list` is to show just the first line of the comment, instead of the last, and then in `just --show command` it would render the whole long-form comment.
It could also be useful to add a `--list --full` or other such flag to request the long-form documentation on the list view as well, if desired (or use the distinction between `-l` and `--list` for this, similar to some tools that use `-h` and `--help` for short/long form help test)
Contributor guide
Research direction
Start at the CLI handling for `just --list` and `just --show command`, then reproduce the example Justfile and compare both outputs. Done means `--list` shows the first documentation line while `--show command` shows the full comment; the optional full-list flag remains a design choice in the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100