Improve the documentation of jj prev

This will hopefully make it clear that `jj prev` does not
move by [OFFSET] relative to `@`, which is a misconception
that I had and I think others may also have.

I am suggesting this change as a result of the vigorous discussion in
these two issues:

- #3426
- #3445

We should make similar changes to `jj next` as well since
it follows similar rules.

cli/src/commands/prev.rs

@@ -20,35 +20,36 @@ use crate::cli_util::{short_commit_hash, CommandHelper};
 use crate::command_error::{user_error, CommandError};
 use crate::commands::next::choose_commit;
 use crate::ui::Ui;
-
-/// Move the working-copy commit to the parent revision
+/// Change the working copy revision relative to the parent revision
 ///
+/// The command creates a new empty working copy revision that is the child of
+/// an ancestor `offset` revisions behind the parent of the current working
+/// copy.
 ///
-/// The command moves you to the parent in a linear fashion.
+/// For example, when the offset is 1:
 ///
 /// ```text
-/// D @  D
-/// |/   |
-/// A => A @
-/// |    |/
-/// B    B
+/// D @      D
+/// |/       |
+/// A   =>   A @
+/// |        |/
+/// B        B
 /// ```
 ///
-/// If `--edit` is passed, it will move the working copy commit
-/// directly to the parent.
+/// If `--edit` is passed, the working copy revision is changed to the parent of
+/// the current working copy revision.
 ///
 /// ```text
-/// D @  D
-/// |/   |
-/// C => @
-/// |    |
-/// B    B
-/// |    |
-/// A    A
-///
-/// If your working-copy commit already has visible children, then `--edit` is
-/// implied.
+/// D @      D
+/// |/       |
+/// C   =>   @
+/// |        |
+/// B        B
+/// |        |
+/// A        A
 /// ```
+/// If the working copy revision already has visible children, then `--edit` is
+/// implied.
 // TODO(#2126): Handle multiple parents, e.g merges.
 #[derive(clap::Args, Clone, Debug)]
 #[command(verbatim_doc_comment)]

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

@@ -128,7 +128,7 @@ To get started, see the tutorial at https://github.com/martinvonz/jj/blob/main/d
 * `obslog` — Show how a change has evolved
 * `operation` — Commands for working with the operation log
 * `parallelize` — Parallelize revisions by making them siblings
-* `prev` — Move the working-copy commit to the parent revision
+* `prev` — Change the working copy revision relative to the parent revision
 * `rebase` — Move revisions to different parent(s)
 * `resolve` — Resolve a conflicted file with an external merge tool
 * `restore` — Restore paths from another revision
@@ -1385,34 +1385,36 @@ several conditions, otherwise the command will fail.
 
 ## `jj prev`
 
-Move the working-copy commit to the parent revision
+Change the working copy revision relative to the parent revision
 
+The command creates a new empty working copy revision that is the child of
+an ancestor `offset` revisions behind the parent of the current working
+copy.
 
-The command moves you to the parent in a linear fashion.
+For example, when the offset is 1:
 
 ```text
-D @  D
-|/   |
-A => A @
-|    |/
-B    B
+D @      D
+|/       |
+A   =>   A @
+|        |/
+B        B
 ```
 
-If `--edit` is passed, it will move the working copy commit
-directly to the parent.
+If `--edit` is passed, the working copy revision is changed to the parent of
+the current working copy revision.
 
 ```text
-D @  D
-|/   |
-C => @
-|    |
-B    B
-|    |
-A    A
-
-If your working-copy commit already has visible children, then `--edit` is
-implied.
+D @      D
+|/       |
+C   =>   @
+|        |
+B        B
+|        |
+A        A
 ```
+If the working copy revision already has visible children, then `--edit` is
+implied.
 
 **Usage:** `jj prev [OPTIONS] [OFFSET]`