[BUG] Clarify usage format for --param flag in help command
- Dominant language
- TypeScript
- Stars
- 272
- Forks
- 375
- Avg merge
- 3h 22m
- Merged PRs (30d)
- 8
Description
### Describe the bug.
The current help description for the `--param` flag (`asyncapi generate fromTemplate --help`) is vague and does not indicate the required format for passing parameters.
Current Help Output:
-p, --param ... Additional param to pass to templates
This seems ambiguous. Users guessing other common formats (like colon separators) will encounter errors. While the CLI provides a helpful error message *after* the failure (`Error: ...It must be in the format of --param name1=value1`), this creates a poor user experience where a user must **fail first** to discover the correct syntax.
**Proposed Solution**
I have verified in the source code (`src/internal/flags/generate/fromTemplate.flags.ts` or `sharedFlags.ts`) that the CLI splits parameters using the `=` character.
I propose updating the flag description to include the example used in the error message.
**Current Code:**
```typescript
param: Flags.string({
char: 'p',
description: 'Additional param to pass to templates',
multiple: true
})
```
Proposed Change:
```typeScript
param: Flags.string({
char: 'p',
description: 'Additional param to pass to templates (e.g., --param sidebarOrganization=byTags)',
multiple: true
}),
```
### Expected behavior
The `--help` documentation should be preventive and self-contained. It should explicitly show the expected `key=value` format so users succeed on their first try.
### Screenshots
**Screenshots**
### How to Reproduce
1. Run `asyncapi generate fromTemplate --help`.
2. Observe the description for `-p, --param`.
3. Try running with a guessed format: `asyncapi generate ... --param key:value`.
4. Observe the error: `Error: Invalid param... It must be in the format of --param name1=value1`.
### 🖥️ Device Information [optional]
- Operating System (OS): Windows
- Browser: N/A
- Browser Version: N/A
### 👀 Have you checked for similar open issues?
- [x] I checked and didn't find similar issue
### 🏢 Have you read the Contributing Guidelines?
- [x] I have read the [Contributing Guidelines](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md)
### Are you willing to work on this issue ?
Yes I am willing to submit a PR!
Contributor guide
Assessment
This issue has not been assessed yet.