casey / casey/just

`just --list` support multi-line documentation comments

Open
#2,684 8 comments 24 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.