Recipe comment display is truncated to only the last line

[luisschwab]

When a recipe has a multi-line comment, the output when running just only shows the last line. For example:

bdk % just
Available recipes:
    build                            # Build the project [alias: b]
    check                            # Check code: formatting, compilation, linting, and commit signature [alias: c]
    fmt                              # Format all code [alias: f]
    pre-push                         # Run pre-push suite: format, check, and test [alias: p]
    test                             # Run all tests for all crates with all features enabled [alias: t]
    verify-standalone crate *args="" # breaking changes from other workspace crates [alias: vs]
    verify-standalone-all *args=""   # Verify all publishable crates can be built standalone [alias: vsa]

# Verify that a crate can be built standalone without workspace dependencies
# This ensures the crate is publishable and doesn't accidentally depend on
# breaking changes from other workspace crates
verify-standalone crate *args="":
    #!/usr/bin/env bash
    set -euo pipefail
    ...

Would be nice to make it always output the first line, or the first line given we have an empty line separating the first line and the rest, as such:

# Verify that a crate can be built standalone without workspace dependencies
#
# This ensures the crate is publishable and doesn't accidentally depend on
# breaking changes from other workspace crates
verify-standalone crate *args="":
    #!/usr/bin/env bash
    set -euo pipefail
    ...

Which should output:

bdk % just
Available recipes:
    build                            # Build the project [alias: b]
    check                            # Check code: formatting, compilation, linting, and commit signature [alias: c]
    fmt                              # Format all code [alias: f]
    pre-push                         # Run pre-push suite: format, check, and test [alias: p]
    test                             # Run all tests for all crates with all features enabled [alias: t]
    verify-standalone crate *args="" # Verify that a crate can be built standalone without workspace dependencies [alias: vs]
    verify-standalone-all *args=""   # Verify all publishable crates can be built standalone [alias: vsa]

[majiayu000]

Hi, I've been looking into this and traced the root cause.

Proposed approach: In the Rust source, find where recipe comments are collected for --list display. Currently the last comment line is retained; change logic to retain the first comment line (or first non-empty line). This likely involves the comment collection in the parser or the listing/formatting module. Add integration tests with multi-line comments verifying first-line display. Check existing tests in the integration test suite for --list output patterns.

I'll open a draft PR shortly. Happy to adjust based on your preference.

[casey]

I think using the first line would probably have been the right thing to do from the beginning, but it would be a somewhat disruptive breaking change at this point.

The doc attribute can be used to explicitly set the doc comment, regardless of which comments precede the recipe:

# This ensures the crate is publishable and doesn't accidentally depend on
# breaking changes from other workspace crates
[doc: "Verify that a crate can be built standalone without workspace dependencies"]
verify-standalone crate *args="":