# HG changeset patch
# User Rik <rik@octave.org>
# Date 1380124414 25200
# Node ID 4f1d827e13022e2f3e2f4265df0fa3c2c5c74655
# Parent  6e21e858d677775c3c32b6202ca61db4799cd3c7
doc: Add to documentation for gca, gcf.

* scripts/plot/gca.m, scripts/plot/gcf.m: Add to documentation.

diff --git a/scripts/plot/gca.m b/scripts/plot/gca.m
--- a/scripts/plot/gca.m
+++ b/scripts/plot/gca.m
@@ -20,8 +20,13 @@
 ## @deftypefn {Function File} {@var{h} =} gca ()
 ## Return a handle to the current axis object.
 ##
-## If no axis object exists, create one and return its handle.  The handle may
-## then be used to examine or set properties of the axes.  For example,
+## The current axis is the default target for graphics output.  In the case
+## of a figure with multiple axes, @code{gca} returns the last created axes
+## or the last axes that was clicked on with the mouse.
+##
+## If no current axes object exists, create one and return its handle.  The
+## handle may then be used to examine or set properties of the axes.  For
+## example,
 ##
 ## @example
 ## @group
@@ -31,8 +36,15 @@
 ## @end example
 ##
 ## @noindent
-## creates an empty axes object, then changes its location and size in the
+## creates an empty axes object and then changes its location and size in the
 ## figure window.
+##
+## Note: To find the current axis without creating a new axes object if it
+## does not exist, query the @qcode{"CurrentAxes"} property of a figure.
+##
+## @example
+## get (gcf, "currentaxes");
+## @end example
 ## @seealso{gcf, gco, gcbf, gcbo, get, set}
 ## @end deftypefn
 
diff --git a/scripts/plot/gcf.m b/scripts/plot/gcf.m
--- a/scripts/plot/gcf.m
+++ b/scripts/plot/gcf.m
@@ -18,23 +18,36 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {@var{h} =} gcf ()
-## Return the current figure handle.
+## Return a handle to the current figure.
 ##
-## If a figure does not exist, create one and return its handle.  The handle
-## may then be used to examine or set properties of the figure.  For example,
+## The current figure is the default target for graphics output.  If multiple
+## figures exist, @code{gcf} returns the last created figure or the last figure
+## that was clicked on with the mouse.
+##
+## If a current figure does not exist, create one and return its handle.  The
+## handle may then be used to examine or set properties of the figure.  For
+## example,
 ##
 ## @example
 ## @group
 ## fplot (@@sin, [-10, 10]);
 ## fig = gcf ();
-## set (fig, "visible", "off");
+## set (fig, "numbertitle", "off", "name", "sin plot")
 ## @end group
 ## @end example
 ##
 ## @noindent
 ## plots a sine wave, finds the handle of the current figure, and then
-## makes that figure invisible.  Setting the visible property of the
-## figure to @qcode{"on"} will cause it to be displayed again.
+## renames the figure window to describe the contents.
+##
+## Note: To find the current figure without creating a new one if it does not
+## exist, query the @qcode{"CurrentFigure"} property of the root graphics
+## object.
+##
+## @example
+## get (0, "currentfigure");
+## @end example
+##
 ## @seealso{gca, gco, gcbf, gcbo, get, set}
 ## @end deftypefn