Project

General

Profile

Actions

Feature #28442

open

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

Improve option descriptions in help output

Added by Oleh Fedorenko over 4 years ago. Updated about 3 years ago.

Status:
New
Priority:
Normal
Assignee:
-
Category:
User experience
Target version:
-
Difficulty:
Triaged:
Yes
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

Actions #1

Updated by Shira Maximov over 4 years ago

  • In Kanboard set to yes

Changing the

Actions #2

Updated by Shira Maximov over 4 years ago

  • In Kanboard deleted (yes)
Actions #3

Updated by Shira Maximov over 4 years ago

  • In Kanboard set to yes

Changing in_kanboard field to yes

Actions #4

Updated by Shira Maximov over 4 years ago

  • In Kanboard deleted (yes)
Actions #5

Updated by Adi Abramovitch about 3 years ago

  • Assignee set to Adi Abramovitch
Actions #6

Updated by Adi Abramovitch about 3 years ago

  • Assignee deleted (Adi Abramovitch)
Actions

Also available in: Atom PDF