Fix documentation of `make-frame' and related variables and hooks

* lisp/frame.el (before-make-frame-hook)
(after-make-frame-functions, frame-inherited-parameters)
(make-frame): Fix doc-strings.
* doc/lispref/frames.texi (Creating Frames): Fix description
of `make-frame' and related variables and hooks.

1 files changed, 34 insertions, 24 deletions

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 6431bbdedb9..f66ecee8e8e 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -112,37 +112,39 @@ window of another Emacs frame.  @xref{Child Frames}.
 * Display Feature Testing::     Determining the features of a terminal.
 @end menu
 
+
 @node Creating Frames
 @section Creating Frames
 @cindex frame creation
 
 To create a new frame, call the function @code{make-frame}.
 
-@deffn Command make-frame &optional alist
+@deffn Command make-frame &optional parameters
 This function creates and returns a new frame, displaying the current
 buffer.
 
-The @var{alist} argument is an alist that specifies frame parameters
-for the new frame.  @xref{Frame Parameters}.  If you specify the
-@code{terminal} parameter in @var{alist}, the new frame is created on
-that terminal.  Otherwise, if you specify the @code{window-system}
-frame parameter in @var{alist}, that determines whether the frame
-should be displayed on a text terminal or a graphical terminal.
-@xref{Window Systems}.  If neither is specified, the new frame is
-created in the same terminal as the selected frame.
-
-Any parameters not mentioned in @var{alist} default to the values in
-the alist @code{default-frame-alist} (@pxref{Initial Parameters});
+The @var{parameters} argument is an alist that specifies frame
+parameters for the new frame.  @xref{Frame Parameters}.  If you specify
+the @code{terminal} parameter in @var{parameters}, the new frame is
+created on that terminal.  Otherwise, if you specify the
+@code{window-system} frame parameter in @var{parameters}, that
+determines whether the frame should be displayed on a text terminal or a
+graphical terminal.  @xref{Window Systems}.  If neither is specified,
+the new frame is created in the same terminal as the selected frame.
+
+Any parameters not mentioned in @var{parameters} default to the values
+in the alist @code{default-frame-alist} (@pxref{Initial Parameters});
 parameters not specified there default from the X resources or its
 equivalent on your operating system (@pxref{X Resources,, X Resources,
-emacs, The GNU Emacs Manual}).  After the frame is created, Emacs
-applies any parameters listed in @code{frame-inherited-parameters}
-(see below) and not present in the argument, taking the values from
-the frame that was selected when @code{make-frame} was called.
+emacs, The GNU Emacs Manual}).  After the frame is created, this
+function applies any parameters specified in
+@code{frame-inherited-parameters} (see below) it has no assigned yet,
+taking the values from the frame that was selected when
+@code{make-frame} was called.
 
 Note that on multi-monitor displays (@pxref{Multiple Terminals}), the
 window manager might position the frame differently than specified by
-the positional parameters in @var{alist} (@pxref{Position
+the positional parameters in @var{parameters} (@pxref{Position
 Parameters}).  For example, some window managers have a policy of
 displaying the frame on the monitor that contains the largest part of
 the window (a.k.a.@: the @dfn{dominating} monitor).
@@ -158,20 +160,28 @@ A normal hook run by @code{make-frame} before it creates the frame.
 @end defvar
 
 @defvar after-make-frame-functions
-An abnormal hook run by @code{make-frame} after it creates the frame.
-Each function in @code{after-make-frame-functions} receives one argument, the
-frame just created.
+An abnormal hook run by @code{make-frame} after it created the frame.
+Each function in @code{after-make-frame-functions} receives one
+argument, the frame just created.
 @end defvar
 
+Note that any functions added to these hooks by your initial file are
+usually not run for the initial frame, since Emacs reads the initial
+file only after creating that frame.  However, if the initial frame is
+specified to use a separate minibuffer frame (@pxref{Minibuffers and
+Frames}), the functions will be run for both, the minibuffer-less and
+the minibuffer frame.
+
 @defvar frame-inherited-parameters
 This variable specifies the list of frame parameters that a newly
 created frame inherits from the currently selected frame.  For each
-parameter (a symbol) that is an element in the list and is not present
-in the argument to @code{make-frame}, the function sets the value of
-that parameter in the created frame to its value in the selected
-frame.
+parameter (a symbol) that is an element in this list and has not been
+assigned earlier when processing @code{make-frame}, the function sets
+the value of that parameter in the created frame to its value in the
+selected frame.
 @end defvar
 
+
 @node Multiple Terminals
 @section Multiple Terminals
 @cindex multiple terminals