magit-diff-dwim: Improve documentation

I wrote this a while ago in response to a user complaining that this
command never does what they mean (dwtm), and have finally decided to
install it after all, because, despite the slight saltiness towards
the end, this actually is useful information.

2 files changed, 36 insertions, 0 deletions

diff --git a/docs/magit.org b/docs/magit.org
index 4d32dd7..d5c327a 100644
--- a/docs/magit.org
+++ b/docs/magit.org
@@ -3105,6 +3105,24 @@ Also see [[man:git-diff]]
 
   Show changes for the thing at point.
 
+  For example, if point is on a commit, show the changes introduced by
+  that commit.  Likewise if point is on the section titled "Unstaged
+  changes", then show those changes in a separate buffer.  Generally
+  speaking, compare the thing at point with the most logical, trivial
+  and (in *any* situation) at least potentially useful other thing it
+  could be compared to.
+
+  When the region selects commits, then compare the two commits at
+  either end.  There are different ways two commits can be compared.
+  In the buffer showing the diff, you can control how the comparison,
+  is done, using "D r" and "D f".
+
+  This function does not always show the changes that you might want
+  to view in any given situation.  You can think of the changes being
+  shown as the smallest common denominator.  There is no AI involved.
+  If this command never does what you want, then ignore it, and instead
+  use the commands that allow you to explicitly specify what you need.
+
 - Key: d r (magit-diff-range) ::
 
   Show differences between two commits.
diff --git a/docs/magit.texi b/docs/magit.texi
index 240e262..d5b9e14 100644
--- a/docs/magit.texi
+++ b/docs/magit.texi
@@ -3871,6 +3871,24 @@ temporary buffer until a suffix is invoked.
 @findex magit-diff-dwim
 Show changes for the thing at point.
 
+For example, if point is on a commit, show the changes introduced by
+that commit.  Likewise if point is on the section titled "Unstaged
+changes", then show those changes in a separate buffer.  Generally
+speaking, compare the thing at point with the most logical, trivial
+and (in @strong{any} situation) at least potentially useful other thing it
+could be compared to.
+
+When the region selects commits, then compare the two commits at
+either end.  There are different ways two commits can be compared.
+In the buffer showing the diff, you can control how the comparison,
+is done, using "D r" and "D f".
+
+This function does not always show the changes that you might want
+to view in any given situation.  You can think of the changes being
+shown as the smallest common denominator.  There is no AI involved.
+If this command never does what you want, then ignore it, and instead
+use the commands that allow you to explicitly specify what you need.
+
 @item @kbd{d r} (@code{magit-diff-range})
 @kindex d r
 @findex magit-diff-range