Clarify the semantics of 'string-pixel-width'

* doc/lispref/display.texi (Size of Displayed Text):
* lisp/emacs-lisp/subr-x.el (string-pixel-width):
* src/xdisp.c (Fwindow_text_pixel_size, Fbuffer_text_pixel_size):
Doc fixes.  (Bug#73129)

3 files changed, 13 insertions, 5 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 9a43ad0568a..c0fbde5d96a 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2238,7 +2238,7 @@ displayed in a given window.  This function is used by
 it contains.
 
 @defun window-text-pixel-size &optional window from to x-limit y-limit mode-lines ignore-line-at-end
-This function returns the size of the text of @var{window}'s buffer in
+This function returns the dimensions of the text of @var{window}'s buffer in
 pixels.  @var{window} must be a live window and defaults to the
 selected one.  The return value is a cons of the maximum pixel-width
 of any text line and the maximum pixel-height of all text lines.  This
@@ -2387,7 +2387,11 @@ meaning as with @code{window-text-pixel-size}.
 
 @defun string-pixel-width string
 This is a convenience function that uses @code{window-text-pixel-size}
-to compute the width of @var{string} (in pixels).
+to compute the width of @var{string} (in pixels).  Caveat: if you call
+this function to measure the width of a string with embedded newlines,
+it will then return the width of the widest substring that does not
+include newlines.  The meaning of this result is the widest line taken
+by the string if inserted into a buffer.
 @end defun
 
 @defun line-pixel-height
diff --git a/lisp/emacs-lisp/subr-x.el b/lisp/emacs-lisp/subr-x.el
index e725c490aba..d5ed934f805 100644
--- a/lisp/emacs-lisp/subr-x.el
+++ b/lisp/emacs-lisp/subr-x.el
@@ -338,7 +338,11 @@ This construct can only be used with lexical binding."
 
 ;;;###autoload
 (defun string-pixel-width (string)
-  "Return the width of STRING in pixels."
+  "Return the width of STRING in pixels.
+
+If you call this function to measure pixel width of a string
+with embedded newlines, it returns the width of the widest
+substring that does not include newlines."
   (declare (important-return-value t))
   (if (zerop (length string))
       0
diff --git a/src/xdisp.c b/src/xdisp.c
index 5add42ef11b..bf7d84cdcb7 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -11774,7 +11774,7 @@ window_text_pixel_size (Lisp_Object window, Lisp_Object from, Lisp_Object to,
 }
 
 DEFUN ("window-text-pixel-size", Fwindow_text_pixel_size, Swindow_text_pixel_size, 0, 7, 0,
-       doc: /* Return the size of the text of WINDOW's buffer in pixels.
+       doc: /* Return the dimensions of the text of WINDOW's buffer in pixels.
 WINDOW must be a live window and defaults to the selected one.  The
 return value is a cons of the maximum pixel-width of any text line and
 the pixel-height of all the text lines in the accessible portion of
@@ -11854,7 +11854,7 @@ screen line that includes TO to the returned height of the text.  */)
 }
 
 DEFUN ("buffer-text-pixel-size", Fbuffer_text_pixel_size, Sbuffer_text_pixel_size, 0, 4, 0,
-       doc: /* Return size of whole text of BUFFER-OR-NAME in WINDOW.
+       doc: /* Return the dimensions of whole text of BUFFER-OR-NAME in WINDOW.
 BUFFER-OR-NAME must specify a live buffer or the name of a live buffer
 and defaults to the current buffer.  WINDOW must be a live window and
 defaults to the selected one.  The return value is a cons of the maximum