Feature #28442
openTracker #27706: Make the options more readable in the command help
Improve option descriptions in help output
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] ORGANIZATIONOrdering 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
Updated by Shira Maximov almost 5 years ago
- In Kanboard set to yes
Changing in_kanboard field to yes