# HG changeset patch
# User Rik <rik@octave.org>
# Date 1379617272 25200
# Node ID ffa7f1caab4eb4cff7c96da43bdc12719141b545
# Parent  0aa77acf22f5140af7387711ef429d7a148fd1b0
Clarify relationship of close, closereq.
Recode closereq to put input validation first.

* scripts/plot/close.m: Change docstring to place details of implementation at
the end.

* scripts/plot/closereq.m: Put input validation first.

diff --git a/scripts/plot/close.m b/scripts/plot/close.m
--- a/scripts/plot/close.m
+++ b/scripts/plot/close.m
@@ -23,10 +23,6 @@
 ## @deftypefnx {Command} {} close all hidden
 ## Close figure window(s).
 ##
-## @code{close} operates by calling the function specified by the
-## @qcode{"closerequestfcn"} property for each figure.  By default, the function
-## @code{closereq} is used.
-##
 ## When called with no arguments, close the current figure.  This is equivalent
 ## to @code{close (gcf)}.  If the input @var{h} is a graphic handle, or vector
 ## of graphics handles, then close each figure in @var{h}.
@@ -37,10 +33,12 @@
 ## If the argument @qcode{"all hidden"} is given then all figures, including
 ## hidden ones, are closed.
 ##
-## Implementation Note: @code{close} calls a function to dispose of the figure.
-## It is possible that the function will delay or abort removing the figure.
-## To remove a figure without executing any callback functions use
-## @code{delete}.
+## Implementation Note: @code{close} operates by calling the function specified
+## by the @qcode{"closerequestfcn"} property for each figure.  By default, the
+## function @code{closereq} is used.  It is possible that the function invoked
+## will delay or abort removing the figure.  To remove a figure without
+## executing any callback functions use @code{delete}.  When writing a callback
+## function to close a window do not use @code{close} to avoid recursion.
 ##
 ## @seealso{closereq, delete}
 ## @end deftypefn
diff --git a/scripts/plot/closereq.m b/scripts/plot/closereq.m
--- a/scripts/plot/closereq.m
+++ b/scripts/plot/closereq.m
@@ -19,6 +19,9 @@
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} closereq ()
 ## Close the current figure and delete all graphics objects associated with it.
+##
+## By default, the @qcode{"closerequestfcn"} property of a new plot figure
+## points to this function.
 ## @seealso{close, delete}
 ## @end deftypefn
 
@@ -26,18 +29,18 @@
 
 function closereq ()
 
-  if (nargin == 0)
-    cf = gcbf ();
-    if (isempty (cf))
-      warning ("closereq: calling closereq from octave prompt is not supported, use 'close' instead");
-      cf = get (0, "currentfigure");
-    endif
-    if (! isempty (cf) && isfigure (cf))
-      delete (cf);
-    endif
-  else
+  if (nargin != 0)
     print_usage ();
   endif
 
+  cf = gcbf ();
+  if (isempty (cf))
+    warning ("closereq: calling closereq from octave prompt is not supported, use 'close' instead");
+    cf = get (0, "currentfigure");
+  endif
+  if (! isempty (cf) && isfigure (cf))
+    delete (cf);
+  endif
+
 endfunction