From: Martin Rudalics Date: Fri, 8 Aug 2014 09:52:59 +0000 (+0200) Subject: Fix some doc-strings in window.c (Bug#18112) (Bug#18194). X-Git-Tag: emacs-24.3.93~14 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=8faa5ee738c269d19071354b63cd64688f6ba101;p=emacs.git Fix some doc-strings in window.c (Bug#18112) (Bug#18194). * window.c (Fwindow_valid_p): Fix doc-string (Bug#18194). (Fwindow_new_total, Fwindow_normal_size, Fwindow_new_normal) (Fwindow_new_pixel, Fset_window_new_pixel) (Fset_window_new_total, Fset_window_new_normal) (Fwindow_resize_apply): Fix doc-strings (see Bug#18112). --- diff --git a/src/ChangeLog b/src/ChangeLog index a3ebe781be5..6272361196c 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,11 @@ +2014-08-08 Martin Rudalics + + * window.c (Fwindow_valid_p): Fix doc-string (Bug#18194). + (Fwindow_new_total, Fwindow_normal_size, Fwindow_new_normal) + (Fwindow_new_pixel, Fset_window_new_pixel) + (Fset_window_new_total, Fset_window_new_normal) + (Fwindow_resize_apply): Fix doc-strings (see Bug#18112). + 2014-08-07 Eli Zaretskii * fontset.c (Finternal_char_font): Recompute basic faces if the diff --git a/src/window.c b/src/window.c index 5c4e2f97a3b..8502e7b022c 100644 --- a/src/window.c +++ b/src/window.c @@ -311,7 +311,7 @@ DEFUN ("windowp", Fwindowp, Swindowp, 1, 1, 0, DEFUN ("window-valid-p", Fwindow_valid_p, Swindow_valid_p, 1, 1, 0, doc: /* Return t if OBJECT is a valid window and nil otherwise. A valid window is either a window that displays a buffer or an internal -window. Deleted windows are not live. */) +window. Windows that have been deleted are not valid. */) (Lisp_Object object) { return WINDOW_VALID_P (object) ? Qt : Qnil; @@ -792,7 +792,10 @@ total width of WINDOW. */) DEFUN ("window-new-total", Fwindow_new_total, Swindow_new_total, 0, 1, 0, doc: /* Return the new total size of window WINDOW. -WINDOW must be a valid window and defaults to the selected one. */) +WINDOW must be a valid window and defaults to the selected one. + +The new total size of WINDOW (see `window-total-size') is that set by +the last call of `set-window-new-total' for WINDOW. */) (Lisp_Object window) { return decode_valid_window (window)->new_total; @@ -801,7 +804,25 @@ WINDOW must be a valid window and defaults to the selected one. */) DEFUN ("window-normal-size", Fwindow_normal_size, Swindow_normal_size, 0, 2, 0, doc: /* Return the normal height of window WINDOW. WINDOW must be a valid window and defaults to the selected one. -If HORIZONTAL is non-nil, return the normal width of WINDOW. */) +If HORIZONTAL is non-nil, return the normal width of WINDOW. + +The normal height of a frame's root window or a window that is +horizontally combined (a window that has a left or right sibling) is +1.0. The normal height of a window that is vertically combined (has a +sibling above or below) is the fraction of the window's height with +respect to its parent. The sum of the normal heights of all windows in a +vertical combination equals 1.0. + +Similarly, the normal width of a frame's root window or a window that is +vertically combined equals 1.0. The normal width of a window that is +horizontally combined is the fraction of the window's width with respect +to its parent. The sum of the normal widths of all windows in a +horizontal combination equals 1.0. + +The normal sizes of windows are used to restore the proportional sizes +of windows after they have been shrunk to their minimum sizes; for +example when a frame is temporarily made very small and afterwards gets +re-enlarged to its previous size. */) (Lisp_Object window, Lisp_Object horizontal) { struct window *w = decode_valid_window (window); @@ -811,7 +832,10 @@ If HORIZONTAL is non-nil, return the normal width of WINDOW. */) DEFUN ("window-new-normal", Fwindow_new_normal, Swindow_new_normal, 0, 1, 0, doc: /* Return new normal size of window WINDOW. -WINDOW must be a valid window and defaults to the selected one. */) +WINDOW must be a valid window and defaults to the selected one. + +The new normal size of WINDOW (see `window-normal-size') is that set by +the last call of `set-window-new-normal' for WINDOW. */) (Lisp_Object window) { return decode_valid_window (window)->new_normal; @@ -819,7 +843,12 @@ WINDOW must be a valid window and defaults to the selected one. */) DEFUN ("window-new-pixel", Fwindow_new_pixel, Swindow_new_pixel, 0, 1, 0, doc: /* Return new pixel size of window WINDOW. -WINDOW must be a valid window and defaults to the selected one. */) +WINDOW must be a valid window and defaults to the selected one. + +The new pixel size of WINDOW is the value set by the last call of +`set-window-new-pixel' for WINDOW. If set correctly, it gets eventually +installed by the function `window-resize-apply' and will be returned by +the functions `window-pixel-height' or `window-pixel-width'. */) (Lisp_Object window) { return decode_valid_window (window)->new_pixel; @@ -3715,6 +3744,10 @@ Return SIZE. Optional argument ADD non-nil means add SIZE to the new pixel size of WINDOW and return the sum. +The new pixel size of WINDOW is used by `window-resize-apply' and, if +that function succeeds, will be subsequently returned by the functions +`window-pixel-height' and `window-pixel-width'. + Note: This function does not operate on any child windows of WINDOW. */) (Lisp_Object window, Lisp_Object size, Lisp_Object add) { @@ -3739,6 +3772,9 @@ Return SIZE. Optional argument ADD non-nil means add SIZE to the new total size of WINDOW and return the sum. +The new total size of WINDOW is used by `window-resize-apply-total' and, +after calling that function, will be returned by `window-total-size'. + Note: This function does not operate on any child windows of WINDOW. */) (Lisp_Object window, Lisp_Object size, Lisp_Object add) { @@ -3758,6 +3794,10 @@ DEFUN ("set-window-new-normal", Fset_window_new_normal, Sset_window_new_normal, WINDOW must be a valid window and defaults to the selected one. Return SIZE. +The new normal size of WINDOW is used by `window-resize-apply' and, if +that function succeeds, will be subsequently returned by the function +`window-normal-size'. + Note: This function does not operate on any child windows of WINDOW. */) (Lisp_Object window, Lisp_Object size) { @@ -4025,9 +4065,14 @@ If FRAME is omitted or nil, it defaults to the selected frame. Optional argument HORIZONTAL omitted or nil means apply requested height values. HORIZONTAL non-nil means apply requested width values. -This function checks whether the requested values sum up to a valid -window layout, recursively assigns the new sizes of all child windows -and calculates and assigns the new start positions of these windows. +The requested size values are those set by `set-window-new-pixel' and +`set-window-new-normal'. This function checks whether the requested +values sum up to a valid window layout, recursively assigns the new +sizes of all child windows and calculates and assigns the new start +positions of these windows. + +Return t if the requested values have been applied correctly, nil +otherwise. Note: This function does not check any of `window-fixed-size-p', `window-min-height' or `window-min-width'. All these checks have to