apple / apple/swift-argument-parser

Proposal: Surface clearer help documentation around the default subcommand

Open
#143 8 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Swift
Stars
3.8k
Forks
411
Avg merge
7d 14h
Merged PRs (30d)
15

Description

Commands with default subcommands do not have discoverable usage information without digging into the subcommand itself. Below, I'll outline the structure of a simple project as well as two proposals for updating the help information for commands that have a default subcommand.

Simply put, a command with a default subcommand likely doesn't have any information it runs itself and, as such, should specify the information that is available by running the default subcommand.

## Structure

For ease of clarity, repeating the structure of my project here:

Command: `zinc`
Subcommands: `lint`, `sync`
Default Subcommand: `sync`

## Proposal 1 - Highlighting the Default Subcommand

### Problem Statement

The output of `zinc --help` is such that the default subcommand is not made clear.

This is what prints:

```
SUBCOMMANDS:
lint Performs basic linting against a Zincfile to identify issues and errors.
sync Syncs local files with remote files as defined by a Zincfile.
```

### Proposed Solution

I'm proposing we highlight the default subcommand somehow:

```
SUBCOMMANDS:
lint Performs basic linting against a Zincfile to identify issues and errors.
sync (default) Syncs local files with remote files as defined by a Zincfile.
```

## Proposal 2 - Prefer Default Subcommand Usage

### Problem Statement

If I specify a default subcommand in my project, while I would allow someone to run `zinc sync `, specifying a default subcommand likely implies that I'm happy with `zinc `. As such, I think that the output of ` --help` should be refined.

Right now, here's what prints out when I run `zinc --help`:

```
OVERVIEW: Zinc is a command-line tool for keeping local files in sync with files hosted outside of your folder or
repository.

USAGE: zinc

OPTIONS:
-h, --help Show help information.

SUBCOMMANDS:
lint Performs basic linting against a Zincfile to identify issues and errors.
sync Syncs local files with remote files as defined by a Zincfile.
```

Here is the output of `zinc sync --help`:

```
OVERVIEW: Syncs local files with remote files as defined by a Zincfile.

USAGE: zinc sync [--file ] [--verbose]

OPTIONS:
-f, --file The Zincfile to parse and use for syncing. (default: Zincfile)
--verbose Logs additional debug messages if enabled.
-h, --help Show help information.
```

### Proposed Solution

I'm not sure what the right answer is here, but I imagine we should see an example of the default command being run, along with additional subcommands still.

I'm not sold on this, but here's an example:

```
OVERVIEW: Zinc is a command-line tool for keeping local files in sync with files hosted outside of your folder or
repository.

USAGE:
zinc --file
zinc

OPTIONS:
-f, --file The Zincfile to parse and use for syncing. (default: Zincfile)
--verbose Logs additional debug messages if enabled.
-h, --help Show help information.

SUBCOMMANDS:
lint Performs basic linting against a Zincfile to identify issues and errors.
sync (default) Syncs local files with remote files as defined by a Zincfile.
```

## Additional Notes

I'd like some additional feedback on the proposed solutions. I'm poking around at a variety of commands that I use day-to-day in my Swift projects as well as some outside of the Swift ecosystem and there's a variety of answers, but almost all at least provide some help documentation for a default subcommand within the help documentation of the command itself if requested.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the issue's `zinc --help` and `zinc sync --help` examples and the two proposed approaches. Determine which default-subcommand behavior the project wants, then verify that help output exposes the default command's usage and still documents other subcommands.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.