Project

General

Profile

Feature #28442

Tracker #27706: Make the options more readable in the command help

Improve option descriptions in help output

Added by Oleh Fedorenko 8 months ago. Updated 8 months ago.

Status:
New
Priority:
Normal
Assignee:
-
Category:
User experience
Target version:
-
Difficulty:
Triaged:
Yes
Bugzilla link:
Pull request:
Team Backlog:
Fixed in Releases:
Found in Releases:
In Kanboard:

Description

First example is generated descriptions `"#{X} to search by"`. The only information it holds is "it is a filter".
See following chunk from `hammer repository list -h`:

#...
--content-view CONTENT_VIEW_NAME Content view name to search by
--content-view-id CONTENT_VIEW_ID content view numeric identifier
--content-view-version CONTENT_VIEW_VERSION_VERSION Content view version number
--content-view-version-content-view-id CONTENT_VIEW_VERSION_CONTENT_VIEW_ID Content view to search by
--content-view-version-id CONTENT_VIEW_VERSION_ID Content view version identifier
--environment ENVIRONMENT_NAME Name to search by
--environment-id ENVIRONMENT_ID
#...
--organization ORGANIZATION_NAME Organization name to search by
--organization-id ORGANIZATION_ID organization ID
--organization-label ORGANIZATION_LABEL Organization label to search by
#...

Also some parameter descriptions (either generated or from apidocs) don't really add more information and only repeat
the option name:

--organization ORGANIZATION_NAME Organization name
--organization-id ORGANIZATION_ID organization ID

Such options are quite self-explanatory and the only benefit for keeping the descriptions is that they're translated.
It might make sense to remove such descriptions.

To avoid repeating descriptions, options could be logically grouped by their semantics:

hammer host list -h
Usage:
hammer host list [OPTIONS]

Options:
Filtering:
--environment[-id] ENVIRONMENT
--hostgroup[-id|-title] HOSTGROUP
--location[-id] LOCATION
--organization[-id|-label] ORGANIZATION

Ordering and pagination:
--order ORDER Sort field and order, eg. ‘name DESC’
--page PAGE Page number, starting at 1
--per-page PER_PAGE Number of results per page to return
--search SEARCH Filter results

-h, --help Print help

History

#1 Updated by Shira Maximov 8 months ago

  • In Kanboard set to yes

Changing the

#2 Updated by Shira Maximov 8 months ago

  • In Kanboard deleted (yes)

#3 Updated by Shira Maximov 8 months ago

  • In Kanboard set to yes

Changing in_kanboard field to yes

#4 Updated by Shira Maximov 8 months ago

  • In Kanboard deleted (yes)

Also available in: Atom PDF