cli: minor updates to jj util completion

A few minor updates after 0f27152 AKA #2945

Specifically, I tried to change the help text so that it looks better as
Markdown. I also reworded the deprecation warning and added a hint.

cli/src/commands/util.rs

@@ -34,15 +34,19 @@ pub(crate) enum UtilCommand {
     ConfigSchema(UtilConfigSchemaArgs),
 }
 
+#[rustfmt::skip]
 /// Print a command-line-completion script
 ///
-/// Apply it by running this:
-/// bash: source <(jj util completion)
-/// fish: jj util completion --fish | source
-/// zsh:
-/// autoload -U compinit
-/// compinit
-/// source <(jj util completion --zsh)
+/// Apply it by running one of these:
+///
+/// - **bash**: `source <(jj util completion)`
+/// - **fish**: `jj util completion --fish | source`
+/// - **zsh**:
+///     ```
+///     autoload -U compinit
+///     compinit
+///     source <(jj util completion --zsh)
+///     ```
 #[derive(clap::Args, Clone, Debug)]
 #[command(verbatim_doc_comment)]
 pub(crate) struct UtilCompletionArgs {
@@ -109,9 +113,10 @@ fn cmd_util_completion(
     let warn = |shell| {
         writeln!(
             ui.warning(),
-            "warning: `jj util completion --{shell}` will be removed in a future version, and \
+            "Warning: `jj util completion --{shell}` will be removed in a future version, and \
              this will be a hard error"
-        )
+        )?;
+        writeln!(ui.hint(), "Hint: Use `jj util completion {shell}` instead")
     };
     let mut buf = vec![];
     let shell = match (args.shell, args.fish, args.zsh, args.bash) {

cli/tests/cli-reference@.md.snap

@@ -1708,13 +1708,16 @@ Infrequently used commands such as for generating shell completions
 
 Print a command-line-completion script
 
-Apply it by running this:
-bash: source <(jj util completion)
-fish: jj util completion --fish | source
-zsh:
-autoload -U compinit
-compinit
-source <(jj util completion --zsh)
+Apply it by running one of these:
+
+- **bash**: `source <(jj util completion)`
+- **fish**: `jj util completion --fish | source`
+- **zsh**:
+    ```
+    autoload -U compinit
+    compinit
+    source <(jj util completion --zsh)
+    ```
 
 **Usage:** `jj util completion [SHELL]`
 

cli/tests/test_shell_completion.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+use insta::assert_snapshot;
+
 use crate::common::TestEnvironment;
 
 pub mod common;
@@ -21,10 +23,12 @@ fn test_deprecated_flags() {
     let test_env = TestEnvironment::default();
     let (stdout, stderr) =
         test_env.jj_cmd_ok(test_env.env_root(), &["util", "completion", "--bash"]);
-    assert_eq!(
+    assert_snapshot!(
         stderr,
-        "warning: `jj util completion --bash` will be removed in a future version, and this will \
-         be a hard error\n"
+        @r###"
+    Warning: `jj util completion --bash` will be removed in a future version, and this will be a hard error
+    Hint: Use `jj util completion bash` instead
+    "###
     );
     assert!(stdout.contains("COMPREPLY"));
 }