Feature Request - Add ability to give a help message for a recipe.

[brass75]

If there is a recipe that takes multiple arguments, some of which are not optional, it would be very useful to have the ability to run just recipe --help and get a more verbose message than what is in doc. For example, I work in a multi-repo environment but all of our repos have the same setup. I would like to have a Justfile at the base directory where all of my repos are that include some testing functions. While the commands are the same the paths have differences based on which repo it is (application, library, or lambda) and I would like to be able to easily have the documentation as to what it should be. In addition, this would be useful to have if a recipe has required arguments and not all of them are passed as a more descriptive manner of telling the user what the arguments need to be rather than just

error: Recipe `esc-uuid` got 0 arguments but takes 1
usage:
    just esc-uuid uuid

[laniakea64]

Sounds similar to https://github.com/casey/just/issues/2373#issuecomment-2355627818

[brass75]

From their comments it seems like the desire to have a help method is in common. Part of what I’m asking for is to improve the error output if arguments are required but not in the call to the recipe. If I were to attempt a PR for this would it be acceptable? (Note they I’m pretty new to rust so it might take a bit to be able to get it together but I’m willing to give it a shot.)

[casey]

Can you give an example of a recipe, the current help message which just gives, and the help message that you'd like? I'd like to understand the use-case more specifically.

[brass75]

I have this recipe:

[doc('''Run coverage for all Python files in a sub-directory.
  <test_path> - subdirectory to run the tests for
  <repo_name> - the source directory for the repo (for fn_sensor_generators it is `sensor_generators`, for the rest it is the repo name)
  <code_dir> - the sub-directory under src|tests where the code lives (i.e. generators, collectors, etc.)''')]
run-coverage test_path repo_name code_dir:
    PYTHONPATH={{ path_to_repo }} pytest --disable-pytest-warnings -l --cov={{ path_to_repo }}/{{ repo_name }}/{{ code_dir }}/{{ test_path }} {{ path_to_repo }}/tests/{{ code_dir }}/{{ test_path }} $@ --cov-report term-missing

for running unit tests with coverage. If I do just list I get:

    # Run coverage for all Python files in a sub-directory.
    #   <test_path> - subdirectory to run the tests for
    #   <repo_name> - the source directory for the repo (for fn_sensor_generators it is `sensor_generators`, for the rest it is the repo name)
    #   <code_dir> - the sub-directory under src|tests where the code lives (i.e. generators, collectors, etc.)
    run-coverage test_path repo_name code_dir

which is confusing because the doc is above the command because it is 3 lines. I would like the doc to be just that first line and the help to be all 4 lines which explains what the parameters are.

If I run it with no parameters I get:

$ j run-coverage                                                                                                                                                             
error: Recipe `run-coverage` got 0 arguments but takes 3
usage:
    just run-coverage test_path repo_name code_dir

which is less than helpful.