Skip to content

docs(shopping-list): document --pantry, --aisle and related flags#354

Merged
dubadub merged 1 commit into
mainfrom
docs/shopping-list-pantry-help
Jun 9, 2026
Merged

docs(shopping-list): document --pantry, --aisle and related flags#354
dubadub merged 1 commit into
mainfrom
docs/shopping-list-pantry-help

Conversation

@dubadub

@dubadub dubadub commented Jun 9, 2026

Copy link
Copy Markdown
Member

Summary

Fleshes out the terse help text for cook shopping-list's --pantry, --aisle, --ignore-pantry and --ignore-references flags so they match the detailed, example-rich style of the other options.

Context

In #333 a user couldn't find/use --pantry. The flag itself was added in #340 (shipped in 0.30.0); the reporter was on 0.29.1. But the issue also flagged that the option was poorly documented in --help. Each of these flags previously had only a one-line entry — this expands them to explain behaviour and the config auto-discovery (./config/ then global config dir).

No behavioural change; documentation only.

Verification

  • cargo build, cargo fmt, cargo clippy all clean
  • cook shopping-list --help renders the expanded entries

Refs #333

The --pantry flag (added in #340, shipped in 0.30.0) had only a terse
one-line help entry, which made it hard to discover and understand —
the complaint raised in #333. Expand the help for --aisle, --pantry,
--ignore-pantry and --ignore-references to describe what each does and
note the config auto-discovery behaviour, matching the detailed style
of the other shopping-list options.

Refs #333
@claude

claude Bot commented Jun 9, 2026

Copy link
Copy Markdown

Review — docs(shopping-list): document --pantry, --aisle and related flags

Summary: Documentation-only PR; no behaviour changes. Overall this is solid and clearly addresses the discoverability gap raised in #333.

What's good

  • All four descriptions are accurate and consistent with how the flags actually work (verified against src/shopping_list.rs).
  • Adding value_hint = clap::ValueHint::FilePath on --aisle and --pantry is a nice bonus — it enables better shell-completion suggestions. Worth calling out in the PR description since it's a functional improvement, not just docs.
  • The cross-reference from --pantry to --ignore-pantry ("Use --ignore-pantry to skip pantry subtraction entirely.") mirrors the style of the recipes positional arg — good consistency.
  • cargo fmt / cargo clippy verification noted.

Minor suggestions

  1. --ignore-references example syntax — The description says @./other.cook to illustrate recipe references. Worth double-checking this matches the actual accepted parser syntax exactly, so new users copying from --help don't paste something that silently fails.

  2. Config dir path on macOS — Both --aisle and --pantry say "global config directory (~/.config/cook/ or the platform equivalent)". macOS uses ~/Library/Application Support/cook/. Spelling out both paths explicitly would be clearer than "platform equivalent" for macOS users reading --help.

  3. --ignore-pantry wording — "skips loading the pantry file altogether" is slightly redundant with "includes every ingredient regardless of what's in the pantry". One of those sentences is enough.

These are all nits — the PR is ready to merge as-is.

@dubadub dubadub merged commit 489279a into main Jun 9, 2026
4 checks passed
@dubadub dubadub deleted the docs/shopping-list-pantry-help branch June 9, 2026 09:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant