Whole-file documentation

[tgross35]

It would be nice if there was a way to document the entire justfile and include it in --list, which would be helpful for overviews or mentioning how commands relate. For example:

##! This handles the setup and running of foo. Note that commands bar
##! and baz interact, and if you run qux you will eventually later need to
##! run quux. If you are just getting started, you probably want corge.

# First recipe
default:
    just --list

# ...

Could render as:

$ just
This handles the setup and running of foo. Note that commands bar
and baz interact, and if you run qux you will eventually later need to
run quux. If you are just getting started, you probably want corge.

Available recipes:

[casey]

I think the lowest impact way to add this would be as a setting:

set usage := """
  This handles the setup and running of foo. Note that commands bar
  and baz interact, and if you run qux you will eventually later need to
  run quux. If you are just getting started, you probably want corge.
"""

And then make just --usage print this when there's no argument, which is currently an error.

I think printing it out with just --list might get annoying.

[tgross35]

Doing something via set makes complete sense.

What if the first line/paragraph acted as a summary and still got printed with just --list? Then --usage could show the whole thing.

[tgross35]

Hm, thinking about things a bit more: What I'd really like is some kind of equivalent to what a lot of commands do with -h vs --help, where -h shows you a summary while --help shows you the full details. Maybe these concepts could map to --list vs --usage?

Using this justfile as an example:

$ just --list
Available recipes:
    decode *paths=all-crashes # Print the result of crashes in the fuzz output directory [alias: d]
    fuzz                      # Build the instrumented executable and fuzz it. See also: `fuzz-parallel`. [alias: f]
    fuzz-attach               # Attach to a running parallel fuzz session [alias: fa]
    fuzz-build                # Create directories and build the executable, but don't start fuzzing. [alias: fb]
    fuzz-parallel *args       # Start fuzzing in parallel. Note this must be stopped with fuzz-parallel-quit (see fuzz-parallel.sh). [alias: fp]
    fuzz-parallel-quit        # Stop parallel fuzzing [alias: fq]
    gen                       # Generate a corpus for fuzzing then run `cmin`
    test                      # Run non-fuzzing tests [alias: t]

If a long form was available then I'd cut down on the amount of detail in the summary:

$ just --list
Launch various useful commands.

Available recipes:
    decode *paths=all-crashes # Print the result of crashes [alias: d]
    fuzz                      # Build and fuzz it  [alias: f]
    fuzz-attach               # Attach to a running parallel fuzz session [alias: fa]
    fuzz-build                # Build a fuzzable executable [alias: fb]
    fuzz-parallel *args       # Start parallel fuzzing [alias: fp]
    fuzz-parallel-quit        # Stop parallel fuzzing [alias: fq]
    gen                       # Generate a corpus for fuzzing then run `cmin`
    test                      # Run non-fuzzing tests [alias: t]

And the long form with --usage could show everything:

$ just --usage
Launch various useful commands.

The following env is available:

* FUZZ_IN_UNMIN: set the unminimmized directory. Defaults to ...
* FUZZ_IN: set the fuzz input directory
* FUZZ_OUT: ...
* FUZZ_BIN: ...

Availailable invocations:

just fuzz
just f
	Build and fuzz

	Creates the executable with instrumentation then invokes single-threaded
	fuzzing. See `fuzz-parallel` to launch multiple fuzzers.

just fuzz-parallel [args...]
just fp [args...]
	Start parallel fuzzing

	Note that unlike single-thread fuzzing, this launches multiple fuzzers in the
	background. They will need to be stopped by running `just fuzz-parallel`

	Arguments:
	  arg1      do something with a very long explanation, so long that
	            it will have to get wrapped.
	  [args...] this gets passed to ioasiodjf oso fosijfo josij ods


just fuzz-parallel-quit
just fq
	Stop parallel fuzzing

	The session should previously have been launched by `fuzz-parallel`

just decode [paths...]
just d [paths...]
	Print the result of crashes.

	This looks in the fuzz output directory to find all 

	Arguments:
	  [paths...] [default: all-crashes]

...

Few thoughts here:

• I'm assuming that for all doc comments, the first line acts as a summary then everything else is a full description.
• With just --usage (no args) I'd like to see all invocations listed. Most commands don't have too many extra details, and it's easier to scroll a bit than to just --usage recipe multiple times.
• I think it would be nice to print aliases as part of usage. There might be a better way than what I have here.