Arvind Kandpal created CASSANDRA-21732:
------------------------------------------
Summary: Add usage examples to nodetool help and fix help output
regressions after the picocli migration
Key: CASSANDRA-21732
URL: https://issues.apache.org/jira/browse/CASSANDRA-21732
Project: Apache Cassandra
Issue Type: Improvement
Reporter: Arvind Kandpal
Assignee: Arvind Kandpal
Many nodetool commands take arguments in a format that is not obvious from the
help text, such as SSTable file lists, token ranges, compound partition keys,
durations, sizes and comma-separated lists. Users often have to read the source
code or search online to find the correct syntax.
For example, the help for compact does not show how to run a user-defined
compaction on more than one SSTable:
nodetool compact --user-defined <file1> <file2>
This ticket adds an EXAMPLES section to the help of such commands. Because the
nodetool docs are generated from the help output (ant gen-nodetool-text), the
examples also appear in the docs.
While working on this, I found that some help output in the default (airline)
layout differs from 5.0 since the move to picocli (CASSANDRA-17445). These are
fixed as part of this ticket.
Proposed changes:
* Show a subcommand's own footer in the default help layout, and add examples
to commands with non-obvious arguments (for example compact, rebuild,
getsstables, snapshot, repair, toppartitions and setguardrailsconfig).
* Show optional positional arguments in brackets and required options without
brackets in SYNOPSIS, as in 5.0.
* Show every line of a positional argument's description. This restores the
5.0 usage text of altertopology, setautorepairconfig and help.
* Do not break words when the synopsis wraps, and add the missing space before
<command> in removenode.
* Correct help text that does not match the code: the setautorepairconfig
parameter name, the truncatehints usage, and the list of valid auth cache names.
* Allow profile start -e to take a comma-separated list, as its help text
already describes.
All changes are limited to help output, except the profile start -e change,
which keeps the existing repeated -e form working.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
