[DocDB] yb-admin help UX Phase 2b: command metadata registry — groups, descriptions, per-command flags (design)

[ag26jan]

Jira Link: DB-23128

Description

Phase 2b of #32640. This issue's body is the design doc, the way #33431 was for Phase 1b; where the sketch in #32640 disagrees with this, this wins.

What 2b delivers

Grouped help and per-operation descriptions. Today yb-admin help prints a flat, numbered list of ~133 names, and help <operation> shows only the syntax line — no statement of what the operation does, and no mention of the global flags that change its behavior (e.g. -exclude_dead silently applies to list_all_tablet_servers but appears in no help surface).

The core design decision: metadata is data, not text

Every command registers today as {name, args string, action, hidden} — nothing else exists to render. 2b's groups, descriptions, and flag associations are new fields on that registry, not prose hardcoded in a print function. This is load-bearing for two later consumers:

• [DocDB] yb-admin: emit a machine-readable operation catalog via 'help --json' #33432 (help --json) becomes a serializer walking the same registry — no re-extraction of structure from formatted text.
• Phase 3 (shell completion, generated docs) generates from the registry the help prints, so they cannot drift.

Proposed schema

Extend ClusterAdminCli::Command and the registration macro with:

Field	Type	Required	Notes
group	enum	yes	One of the taxonomy below; the enum forces every command into exactly one group.
description	string	yes	One line, see style rules.
flags	list of flag names	no	Global gflags that change this command's behavior (e.g. exclude_dead). Rendered in help <op>; validated at startup against the registered gflags so a typo fails fast in tests, not silently in help.
example	string	no	A single invocation, only where the syntax line alone is misleading.

Commands without the new fields must keep compiling during the population batches (see Rollout), rendering exactly as today; requiredness is enforced by a test that fails on unpopulated visible commands once population completes.

Group taxonomy

Reuse the docs page's grouping (docs.yugabyte.com/stable/admin/yb-admin) so help and docs tell one story:

Universe and cluster · Table · Backup and snapshot · Multi-zone and multi-region deployment · Read replica deployment · Security · Change Data Capture (CDC) · xCluster Replication · Decommissioning · Cluster balancing · Upgrade

Plus one addition: Meta (help itself, and anything else about yb-admin rather than the cluster). Commands the docs page omits get placed by function during population; any that fit nowhere are a signal to revisit the taxonomy in review, not to add a "Misc" dumping ground.

Description style rules

Settled here once so 133 descriptions don't need per-line style debate in review:

• One line, ≤ 80 characters, verb-first, no trailing period: Delete a table and all of its tablets.
• Present tense, imperative mood, no "This command…" prefix.
• Where the docs page already describes the command, start from its wording; diverge only to meet the length rule.

Rendering

• yb-admin help: operations listed under group headers (taxonomy order above), keeping the existing one-line-per-operation cap and numbering semantics from 1b-b.
• yb-admin help <operation>: description line above the existing Usage line; applicable flags listed after it as -flag_name: <gflag help text> (help text comes from the gflag definition — not duplicated in the registry).
• yb-admin help <filter> (substring listing): unchanged flat list — a filtered view is already a selection, and grouping fragments of groups adds noise.

Rollout

1. Schema PR: struct/macro extension, startup validation, rendering with fallback, and one exemplar group fully populated (Backup and snapshot, the largest coherent group). All design debate happens here.
2. Population batches: one group per PR, mechanical after the exemplar. They serialize on the same file; each is a small review.
3. Completion test flips on (every visible command populated) in the final batch.

Each PR stacks on the current review stack top (#33448) until the stack merges — same-file changes cannot land independently.

Open questions

1. Does group justify grouping in the full dump fallback surfaces too (--helpfull is out of scope; the 1b-b overview is not), or only in help?
2. flags as flag-name strings validated at startup vs. a registration-time link to the gflag object — strings are simpler; is startup validation enough?
3. Should the docs page's yb-admin tables eventually be generated from help --json ([DocDB] yb-admin: emit a machine-readable operation catalog via 'help --json' #33432) instead of hand-maintained? Out of scope here, but the schema should not preclude it.

Non-goals

• No change to any command's name, syntax, argument order, or behavior.
• No JSON output in this phase ([DocDB] yb-admin: emit a machine-readable operation catalog via 'help --json' #33432 consumes the registry afterwards).
• No new full-catalog text surface ([DocDB] Improve yb-admin help UX with progressive disclosure #32640 decision 6).

Issue Type

kind/enhancement

Warning: Please confirm that this issue does not contain any sensitive information

• I confirm this issue does not contain any sensitive information.