fix: allow blank comment lines in #USAGE blocks#381
Merged
Conversation
Previously, the parser would stop reading #USAGE comments as soon as it encountered any non-#USAGE line, including blank comment lines like "#". This prevented users from adding whitespace for readability in their USAGE blocks. This change allows blank comment lines (lines matching `^(?:#|//|::)\s*$`) to be skipped while continuing to parse subsequent #USAGE lines. Example that now works: ```bash #!/bin/bash #USAGE long_about """ #USAGE Description #USAGE """ # #USAGE flag "-t --tail" help="Follow logs" ``` Before this fix, the blank "#" line would cause parsing to stop, and the "--tail" flag would not be recognized.
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR fixes a bug in the USAGE parser that prevented blank comment lines within #USAGE blocks. Previously, the parser would stop reading when encountering blank comment lines (like #, //, or ::), which made it impossible to add whitespace for readability in multi-line USAGE blocks.
Key changes:
- Modified the comment parser to recognize and skip blank comment lines while continuing to parse subsequent #USAGE declarations
- Added a regex pattern to detect blank comment lines across different comment styles (#, //, ::)
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #381 +/- ##
==========================================
- Coverage 69.04% 67.36% -1.68%
==========================================
Files 45 45
Lines 4436 4456 +20
Branches 4436 4456 +20
==========================================
- Hits 3063 3002 -61
- Misses 985 1001 +16
- Partials 388 453 +65 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Added comprehensive tests to verify that blank comment lines (e.g., "#", "//", "::") don't stop the USAGE parser. Tests verify: - Help output shows all args/flags despite blank lines - Flags and arguments parse correctly with blank lines present - Default values work correctly - Multiple consecutive blank lines are handled The test script examples/test-blank-comment-lines.sh demonstrates a real-world use case with: - long_about block followed by blank line - Multiple blank lines between flags - All args/flags parsing correctly despite the blank lines
84601e2 to
2f13e75
Compare
Merged
jdx
pushed a commit
that referenced
this pull request
Nov 12, 2025
## [2.8.0](https://github.com/jdx/usage/compare/v2.7.0..v2.8.0) - 2025-11-12 ### 🚀 Features - add examples section to markdown and manpage generation by [@jdx](https://github.com/jdx) in [#380](#380) - add examples support to spec-level by [@jdx](https://github.com/jdx) in [#382](#382) ### 🐛 Bug Fixes - allow blank comment lines in #USAGE blocks by [@jdx](https://github.com/jdx) in [#381](#381)
tmeijn
pushed a commit
to tmeijn/dotfiles
that referenced
this pull request
Nov 14, 2025
This MR contains the following updates: | Package | Update | Change | |---|---|---| | [usage](https://github.com/jdx/usage) | minor | `2.6.0` -> `2.8.0` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>jdx/usage (usage)</summary> ### [`v2.8.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#280---2025-11-12) [Compare Source](jdx/usage@v2.7.0...v2.8.0) ##### 🚀 Features - add examples section to markdown and manpage generation by [@​jdx](https://github.com/jdx) in [#​380](jdx/usage#380) - add examples support to spec-level by [@​jdx](https://github.com/jdx) in [#​382](jdx/usage#382) ##### 🐛 Bug Fixes - allow blank comment lines in #USAGE blocks by [@​jdx](https://github.com/jdx) in [#​381](jdx/usage#381) ### [`v2.7.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#270---2025-11-11) [Compare Source](jdx/usage@v2.6.0...v2.7.0) ##### 🚀 Features - support bracketed header syntax by [@​okuuva](https://github.com/okuuva) in [#​377](jdx/usage#377) ##### 📚 Documentation - Fix VitePress build error in markdown documentation by [@​jdx](https://github.com/jdx) in [#​378](jdx/usage#378) ##### 🔍 Other Changes - integrate clap-sort to enforce alphabetical subcommand ordering by [@​jdx](https://github.com/jdx) in [#​370](jdx/usage#370) ##### 📦️ Dependency Updates - lock file maintenance by [@​renovate\[bot\]](https://github.com/renovate\[bot]) in [#​372](jdx/usage#372) - update rust crate clap-sort to v1.0.3 by [@​renovate\[bot\]](https://github.com/renovate\[bot]) in [#​373](jdx/usage#373) - update rust crate ctor to v0.6.1 by [@​renovate\[bot\]](https://github.com/renovate\[bot]) in [#​374](jdx/usage#374) - lock file maintenance by [@​renovate\[bot\]](https://github.com/renovate\[bot]) in [#​375](jdx/usage#375) ##### New Contributors - [@​okuuva](https://github.com/okuuva) made their first contribution in [#​377](jdx/usage#377) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0MS4xNzMuMSIsInVwZGF0ZWRJblZlciI6IjQxLjE3My4xIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6WyJSZW5vdmF0ZSBCb3QiXX0=-->
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes a bug where the USAGE parser would stop reading #USAGE comments when encountering blank comment lines (e.g.,
#,//, or::). This prevented users from adding whitespace for readability in their USAGE blocks.Problem
Previously, when parsing file-based USAGE specs, the parser would stop as soon as it encountered any line that didn't match the
#USAGEpattern, including blank comment lines. This caused issues like:In this example, the blank
#line after the closing"""would cause parsing to stop, and the--tailflag would not be recognized.Solution
Modified
extract_usage_from_comments()inlib/src/spec/mod.rsto skip blank comment lines (matching^(?:#|//|::)\s*$) while continuing to parse subsequent #USAGE lines.Testing
Added logic to detect and skip blank comment lines while preserving the existing behavior of stopping when encountering non-comment or non-USAGE content.
The fix allows:
🤖 Generated with Claude Code
Note
Teach USAGE comment parser to skip blank comment lines and add example + tests validating help, execution, and defaults.
extract_usage_from_commentsinlib/src/spec/mod.rsto ignore blank comment lines usingblank_comment_regexand continue parsing subsequentUSAGElines.examples/test-blank-comment-lines.shdemonstrating blank comment lines within#USAGEblocks.cli/tests/examples.rscovering help output, execution with flags, and defaults for the new example.Written by Cursor Bugbot for commit 2f13e75. This will update automatically on new commits. Configure here.