Clarify documentation of functions that use the default face

* lisp/simple.el (default-font-height, default-font-width)
(default-line-height): Say in the doc strings that the default
face these functions use is for the currently selected frame.

* doc/lispref/display.texi (Attribute Functions)
(Low-Level Font): Document more clearly the dependence of the
results of 'face-font', 'default-font-width', and
'default-font-height' on the frame's definition of the default
face.

2 files changed, 14 insertions, 6 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 1f7cc93c9c4..fa81b2e9538 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2893,7 +2893,7 @@ This function returns the name of the font of face @var{face}.
 
 If the optional argument @var{frame} is specified, it returns the name
 of the font of @var{face} for that frame.  If @var{frame} is omitted or
-@code{nil}, the selected frame is used.  And, in this case, if the
+@code{nil}, the selected frame is used.  In the latter case, if the
 optional third argument @var{character} is supplied, it returns the font
 name used for @var{character}.
 @end defun
@@ -3934,12 +3934,14 @@ was remapped.  @xref{Face Remapping}.
 
 @defun default-font-width
 This function returns the average width in pixels of the font used by
-the current buffer's default face.
+the current buffer's default face, as that face is defined for the
+selected frame.
 @end defun
 
 @defun default-font-height
 This function returns the height in pixels of the font used by the
-current buffer's default face.
+current buffer's default face, as that face is defined for the
+selected frame.
 @end defun
 
 @defun window-font-width &optional window face
diff --git a/lisp/simple.el b/lisp/simple.el
index 5e4cd8f5bc0..67ddab3d343 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -6194,7 +6194,9 @@ lines."
   "Return the height in pixels of the current buffer's default face font.
 
 If the default font is remapped (see `face-remapping-alist'), the
-function returns the height of the remapped face."
+function returns the height of the remapped face.
+This function uses the definition of the default face for the currently
+selected frame."
   (let ((default-font (face-font 'default)))
     (cond
      ((and (display-multi-font-p)
@@ -6209,7 +6211,9 @@ function returns the height of the remapped face."
   "Return the width in pixels of the current buffer's default face font.
 
 If the default font is remapped (see `face-remapping-alist'), the
-function returns the width of the remapped face."
+function returns the width of the remapped face.
+This function uses the definition of the default face for the currently
+selected frame."
   (let ((default-font (face-font 'default)))
     (cond
      ((and (display-multi-font-p)
@@ -6228,7 +6232,9 @@ function returns the width of the remapped face."
   "Return the pixel height of current buffer's default-face text line.
 
 The value includes `line-spacing', if any, defined for the buffer
-or the frame."
+or the frame.
+This function uses the definition of the default face for the currently
+selected frame."
   (let ((dfh (default-font-height))
         (lsp (if (display-graphic-p)
                  (or line-spacing