Improve documentation of some posn-* functions

* lisp/subr.el (posn-object-x-y): Doc fix.

* doc/lispref/commands.texi (Click Events): More accurate
documentation of what are DX and DY in POSITION.

2 files changed, 12 insertions, 7 deletions

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 377b433cae5..662de29d45a 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1676,10 +1676,14 @@ as returned by @code{find-image} (@pxref{Defining Images}); otherwise
 this is @code{nil}.
 
 @item @var{dx}, @var{dy}
-These are the pixel coordinates of the click, relative to the top left
-corner of @var{object}, which is @code{(0 . 0)}.  If @var{object} is
-@code{nil}, which stands for a buffer, the coordinates are relative to
-the top left corner of the character glyph clicked on.
+These are the pixel offsets of the click relative to the top left
+corner of the @var{object}'s glyph that is the nearest one to the
+click. The relevant @var{object}s can be either a buffer, or a string,
+or an image, see above.  If @var{object} is @code{nil} or a string,
+the coordinates are relative to the top left corner of the character
+glyph clicked on.  Note that the offsets are always zero on text-mode
+frames, when @var{object} is @code{nil}, since each glyph there is
+considered to have exactly 1x1 pixel dimensions.
 
 @item @var{width}, @var{height}
 If the click is on a character, either from buffer text or from
diff --git a/lisp/subr.el b/lisp/subr.el
index 261ec512d89..4f671de918b 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -1792,10 +1792,11 @@ and `event-end' functions."
   (or (posn-image position) (posn-string position)))
 
 (defsubst posn-object-x-y (position)
-  "Return the x and y coordinates relative to the object of POSITION.
+  "Return the x and y coordinates relative to the glyph of object of POSITION.
 The return value has the form (DX . DY), where DX and DY are
-given in pixels.  POSITION should be a list of the form returned
-by `event-start' and `event-end'."
+given in pixels, and they are relative to the top-left corner of
+the clicked glyph of object at POSITION.  POSITION should be a
+list of the form returned by `event-start' and `event-end'."
   (nth 8 position))
 
 (defsubst posn-object-width-height (position)