docs: mark KDL code blocks as KDL and use correct inline-comment `//` by muzimuzhi · Pull Request #536 · jdx/usage

muzimuzhi · 2026-03-11T10:12:54Z

No description provided.

greptile-apps

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

codecov · 2026-03-11T10:14:28Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.94%. Comparing base (7562574) to head (a5960dd).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #536   +/-   ##
=======================================
  Coverage   77.94%   77.94%           
=======================================
  Files          48       48           
  Lines        6682     6682           
  Branches     6682     6682           
=======================================
  Hits         5208     5208           
  Misses       1114     1114           
  Partials      360      360

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot

Pull request overview

This PR updates the documentation examples for usage specs to use KDL-specific Markdown fences and KDL comment syntax, improving correctness and syntax highlighting across the spec reference docs.

Changes:

Switch fenced code blocks from sh to kdl for KDL usage spec examples.
Replace # ... comments inside KDL snippets with // ... to match KDL comment syntax.
Apply these updates across the main spec page and multiple reference pages (arg/cmd/flag/complete).

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/spec/reference/index.md	Converts KDL example fences to `kdl` and updates in-snippet comments to `//`.
docs/spec/reference/flag.md	Converts KDL example fences to `kdl` and updates in-snippet comments to `//`.
docs/spec/reference/complete.md	Converts some KDL example fences to `kdl` and updates in-snippet comments to `//` (one `sh` fence remains).
docs/spec/reference/cmd.md	Converts KDL example fences to `kdl` and updates in-snippet comments to `//`.
docs/spec/reference/arg.md	Converts KDL example fences to `kdl` and updates in-snippet comments to `//`.
docs/spec/index.md	Converts KDL example fences to `kdl` and updates in-snippet comments to `//`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

greptile-apps

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

gemini-code-assist · 2026-03-11T10:50:50Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the accuracy and presentation of KDL code examples within the project's documentation. By explicitly marking KDL code blocks and using the correct // inline comment syntax, the changes improve syntax highlighting and ensure the examples are technically precise, making the documentation clearer and more helpful for users.

Highlights

Documentation Clarity: Updated KDL code block language specifiers from sh to kdl across multiple documentation files to ensure proper syntax highlighting and accurate representation.
KDL Comment Syntax: Corrected KDL inline comment syntax from # to // in all KDL code examples within the documentation for consistency and correctness.

Changelog

docs/spec/index.md
- Updated code block language specifiers to kdl.
- Replaced # comments with //.
docs/spec/reference/arg.md
- Updated code block language specifiers to kdl.
- Replaced # comments with //.
docs/spec/reference/cmd.md
- Updated code block language specifiers to kdl.
- Replaced # comments with //.
docs/spec/reference/complete.md
- Updated code block language specifiers to kdl.
- Replaced # comments with //.
docs/spec/reference/flag.md
- Updated code block language specifiers to kdl.
- Replaced # comments with //.
- Corrected a typo in a long_help attribute.
docs/spec/reference/index.md
- Updated code block language specifiers to kdl.
- Replaced # comments with //.

Activity

No specific activity has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request correctly updates the documentation to mark KDL code blocks with the kdl language identifier and use the appropriate // comment syntax. The changes are consistent and improve the accuracy and readability of the KDL examples across all modified files.

_{Note: Security Review has been skipped due to the limited scope of the PR.}

@jdx

⚠️ **CAUTION: this is a major update, indicating a breaking change!** ⚠️ This MR contains the following updates: | Package | Update | Change | |---|---|---| | [usage](https://github.com/jdx/usage) | major | `2.18.2` → `3.2.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> ### [`v3.2.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#320---2026-03-23) [Compare Source](jdx/usage@v3.1.0...v3.2.0) ##### 🚀 Features - Support env-backed choices with `choices env=...` by [@mustafa0x](https://github.com/mustafa0x) in [#548](jdx/usage#548) ##### 🐛 Bug Fixes - **(zsh)** escape parentheses and brackets in completion descriptions by [@jdx](https://github.com/jdx) in [#559](jdx/usage#559) ##### New Contributors - [@mustafa0x](https://github.com/mustafa0x) made their first contribution in [#548](jdx/usage#548) ### [`v3.1.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#310---2026-03-22) [Compare Source](jdx/usage@v3.0.0...v3.1.0) ##### 🚀 Features - **(cli)** render all doc-related fields in --help output by [@jdx](https://github.com/jdx) in [#554](jdx/usage#554) - **(cli)** support reading spec from stdin via --file - by [@jdx](https://github.com/jdx) in [#555](jdx/usage#555) ##### 🐛 Bug Fixes - **(zsh)** remove trailing space from completions and add directory slash by [@jdx](https://github.com/jdx) in [#556](jdx/usage#556) - use field assignment for non-exhaustive Spec in benchmarks by [@jdx](https://github.com/jdx) in [#552](jdx/usage#552) ##### 📦️ Dependency Updates - update apple-actions/import-codesign-certs digest to [`fe74d46`](jdx/usage@fe74d46) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#550](jdx/usage#550) - update codecov/codecov-action digest to [`1af5884`](jdx/usage@1af5884) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#551](jdx/usage#551) - lock file maintenance by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#547](jdx/usage#547) ### [`v3.0.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#300---2026-03-13) [Compare Source](jdx/usage@v2.18.2...v3.0.0) ##### 🚀 Features - **(spec)** **breaking** add support for license, before/after help metadata by [@jdx](https://github.com/jdx) in [#542](jdx/usage#542) ##### 🐛 Bug Fixes - **(cobra)** escape newlines, tabs, and carriage returns in kdlQuoteAlways by [@thecodesmith](https://github.com/thecodesmith) in [#539](jdx/usage#539) - bump major version for breaking changes in release automation by [@jdx](https://github.com/jdx) in [#544](jdx/usage#544) - add custom\_major\_increment\_regex for breaking change detection by [@jdx](https://github.com/jdx) in [#545](jdx/usage#545) - handle all breaking change commit formats in major bump regex by [@jdx](https://github.com/jdx) in [27e1ab1](jdx/usage@27e1ab1) - normalize breaking change commit format in preprocessor by [@jdx](https://github.com/jdx) in [aa72b92](jdx/usage@aa72b92) ##### 📚 Documentation - add argparse-usage integration by [@jdx](https://github.com/jdx) in [#531](jdx/usage#531) - mark KDL code blocks as KDL and use correct inline-comment `//` by [@muzimuzhi](https://github.com/muzimuzhi) in [#536](jdx/usage#536) - fix include syntax to match implementation by [@jdx](https://github.com/jdx) in [#540](jdx/usage#540) - consolidate integration list to single source by [@jdx](https://github.com/jdx) in [#541](jdx/usage#541) - fix link to integrations by [@muzimuzhi](https://github.com/muzimuzhi) in [#543](jdx/usage#543) ##### 🛡️ Security - **(deps)** update dependency eslint to v10 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#526](jdx/usage#526) ##### 🔍 Other Changes - Added an integration with ruby's OptionParser by [@packrat386](https://github.com/packrat386) in [#533](jdx/usage#533) ##### 📦️ Dependency Updates - update actions/setup-node digest to [`53b8394`](jdx/usage@53b8394) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#525](jdx/usage#525) - update jdx/mise-action action to v3 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#528](jdx/usage#528) - update rust crate roff to v1 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#529](jdx/usage#529) ##### New Contributors - [@thecodesmith](https://github.com/thecodesmith) made their first contribution in [#539](jdx/usage#539) - [@packrat386](https://github.com/packrat386) made their first contribution in [#533](jdx/usage#533) </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. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

docs: mark KDL code blocks as KDL and use correct inline-comment //

7a612c6

Copilot AI review requested due to automatic review settings March 11, 2026 10:12

greptile-apps Bot reviewed Mar 11, 2026

View reviewed changes

Copilot started reviewing on behalf of muzimuzhi March 11, 2026 10:13 View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

Comment thread docs/spec/reference/complete.md

Comment thread docs/spec/reference/flag.md Outdated

Comment thread docs/spec/reference/arg.md

Apply suggestions from review

a5960dd

muzimuzhi mentioned this pull request Mar 11, 2026

Unsupported top-level metadata license, (before|after)_help, (before|after)_long_help #537

Closed

greptile-apps Bot reviewed Mar 11, 2026

View reviewed changes

gemini-code-assist Bot reviewed Mar 11, 2026

View reviewed changes

jdx merged commit 15a13d3 into jdx:main Mar 13, 2026
7 checks passed

mise-en-dev mentioned this pull request Mar 13, 2026

chore: release v3.0.0 #527

Merged

muzimuzhi deleted the docs/fix-kdl-comment branch March 13, 2026 13:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: mark KDL code blocks as KDL and use correct inline-comment `//`#536

docs: mark KDL code blocks as KDL and use correct inline-comment `//`#536
jdx merged 2 commits intojdx:mainfrom
muzimuzhi:docs/fix-kdl-comment

muzimuzhi commented Mar 11, 2026

Uh oh!

greptile-apps Bot left a comment

Uh oh!

codecov Bot commented Mar 11, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot left a comment

Uh oh!

gemini-code-assist Bot commented Mar 11, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

muzimuzhi commented Mar 11, 2026

Uh oh!

greptile-apps Bot left a comment

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot left a comment

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot commented Mar 11, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov Bot commented Mar 11, 2026 •

edited

Loading