# HG changeset patch
# User Rik <octave@nomad.inbox5.com>
# Date 1323205757 28800
# Node ID 5f0bb45e615c0732adcda1a420c30b85d265403c
# Parent  15400d5deb1c249d44b54774b66011095c9710d8
doc: Update documentation for functions returning a graphics handle h (Bug #34761)

* voronoi.m, image.m, imagesc.m, imshow.m, area.m, bar.m, barh.m, clabel.m,
clf.m, compass.m, ezcontour.m, ezcontourf.m, ezmesh.m, ezmeshc.m, ezplot.m,
ezplot3.m, ezpolar.m, ezsurf.m, ezsurfc.m, feather.m, fill.m, findall.m,
findobj.m, loglog.m, mesh.m, pareto.m, patch.m, pie.m, pie3.m, plot.m, polar.m,
quiver.m, quiver3.m, rectangle.m, ribbon.m, rose.m, scatter.m, scatter3.m,
semilogx.m, semilogy.m, slice.m, stem.m, surf.m, surface.m, text.m, title.m,
trimesh.m, triplot.m, trisurf.m, xlabel.m, ylabel.m, zlabel.m:
Update documentation for functions returning a graphics handle h.

diff -r 15400d5deb1c -r 5f0bb45e615c .hgsubstate
--- a/.hgsubstate	Mon Dec 05 17:13:35 2011 -0800
+++ b/.hgsubstate	Tue Dec 06 13:09:17 2011 -0800
@@ -1,1 +1,1 @@
-ff549c078493ea86e7bd87526db276a1b94a411a gnulib
+bb052d4a7416accaad0747e84bd2a0accbfcf923 gnulib
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/geometry/voronoi.m
--- a/scripts/geometry/voronoi.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/geometry/voronoi.m	Tue Dec 06 13:09:17 2011 -0800
@@ -36,7 +36,7 @@
 ## @url{http://www.qhull.org/html/qh-quick.htm#options}.
 ##
 ## If a single output argument is requested then the Voronoi diagram will be
-## plotted and a graphics handle to the plot is returned.
+## plotted and a graphics handle @var{h} to the plot is returned.
 ## [@var{vx}, @var{vy}] = voronoi(@dots{}) returns the Voronoi vertices
 ## instead of plotting the diagram.
 ##
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/image/image.m
--- a/scripts/image/image.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/image/image.m	Tue Dec 06 13:09:17 2011 -0800
@@ -19,6 +19,7 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} image (@var{img})
 ## @deftypefnx {Function File} {} image (@var{x}, @var{y}, @var{img})
+## @deftypefnx {Function File} {@var{h} =} image (@dots{})
 ## Display a matrix as a color image.  The elements of @var{img} are indices
 ## into the current colormap, and the colormap will be scaled so that the
 ## extremes of @var{img} are mapped to the extremes of the colormap.
@@ -35,6 +36,8 @@
 ## an image and an ordinary plot need to be overlaid.  The recommended
 ## solution is to display the image and then plot the reversed ydata
 ## using, for example, @code{flipud (ydata,1)}.
+##
+## The optional return value @var{h} is a graphics handle to the image.
 ## @seealso{imshow, imagesc, colormap}
 ## @end deftypefn
 
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/image/imagesc.m
--- a/scripts/image/imagesc.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/image/imagesc.m	Tue Dec 06 13:09:17 2011 -0800
@@ -32,6 +32,7 @@
 ## values for the respective axes, or as values for each row and column
 ## of the matrix @var{A}.
 ##
+## The optional return value @var{h} is a graphics handle to the image.
 ## @seealso{image, imshow, caxis}
 ## @end deftypefn
 
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/image/imshow.m
--- a/scripts/image/imshow.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/image/imshow.m	Tue Dec 06 13:09:17 2011 -0800
@@ -23,6 +23,7 @@
 ## @deftypefnx {Function File} {} imshow (@var{rgb}, @dots{})
 ## @deftypefnx {Function File} {} imshow (@var{filename})
 ## @deftypefnx {Function File} {} imshow (@dots{}, @var{string_param1}, @var{value1}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} imshow (@dots{})
 ## Display the image @var{im}, where @var{im} can be a 2-dimensional
 ## (gray-scale image) or a 3-dimensional (RGB image) matrix.
 ##
@@ -44,6 +45,8 @@
 ## @item "displayrange"
 ## @var{value1} is the display range as described above.
 ## @end table
+##
+## The optional return value @var{h} is a graphics handle to the image.
 ## @seealso{image, imagesc, colormap, gray2ind, rgb2ind}
 ## @end deftypefn
 
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/area.m
--- a/scripts/plot/area.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/area.m	Tue Dec 06 13:09:17 2011 -0800
@@ -33,9 +33,11 @@
 ## @code{1 : rows (@var{y})}.  A value @var{lvl} can be defined that determines
 ## where the base level of the shading under the curve should be defined.
 ##
-## Additional arguments to the @code{area} function are passed to the
-## @code{patch}.  The optional return value @var{h} provides a handle to
-## area series object representing the patches of the areas.
+## Additional arguments to the @code{area} function are passed to
+## @code{patch}.
+##
+## The optional return value @var{h} is a graphics handle to the hggroup
+## object representing the area patch objects.
 ## @seealso{plot, patch}
 ## @end deftypefn
 
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/bar.m
--- a/scripts/plot/bar.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/bar.m	Tue Dec 06 13:09:17 2011 -0800
@@ -36,7 +36,7 @@
 ## argument, which can take the values @code{"grouped"} (the default),
 ## or @code{"stacked"}.
 ##
-## The optional return value @var{h} provides a handle to the "bar series"
+## The optional return value @var{h} is a handle to the created "bar series"
 ## object with one handle per column of the variable @var{y}.  This
 ## series allows common elements of the group of bar series objects to
 ## be changed in a single bar series and the same properties are changed
@@ -93,3 +93,7 @@
   varargout = cell (nargout, 1);
   [varargout{:}] = __bar__ (true, "bar", varargin{:});
 endfunction
+
+
+%% FIXME: Need demo or test for function
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/barh.m
--- a/scripts/plot/barh.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/barh.m	Tue Dec 06 13:09:17 2011 -0800
@@ -36,13 +36,13 @@
 ## argument, which can take the values @code{"grouped"} (the default),
 ## or @code{"stacked"}.
 ##
-## The optional return value @var{h} provides a handle to the bar series
-## object.  See @code{bar} for a description of the use of the bar series.
-##
 ## The optional input handle @var{h} allows an axis handle to be passed.
 ## Properties of the patch graphics object can be changed using
 ## @var{prop}, @var{val} pairs.
 ##
+## The optional return value @var{h} is a graphics handle to the created
+## bar series object.  See @code{bar} for a description of the use of the
+## bar series.
 ## @seealso{bar, plot}
 ## @end deftypefn
 
@@ -52,3 +52,7 @@
   varargout = cell (nargout, 1);
   [varargout{:}] = __bar__ (false, "barh", varargin{:});
 endfunction
+
+
+%% FIXME: Need demo or test for function
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/clabel.m
--- a/scripts/plot/clabel.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/clabel.m	Tue Dec 06 13:09:17 2011 -0800
@@ -39,9 +39,10 @@
 ## on a contour (in points) to be specified.  The default is 144 points, or 2
 ## inches.
 ##
-## The returned value @var{h} is the set of text object that represent the
-## contour labels.  The "userdata" property of the text objects contains the
-## numerical value of the contour label.
+## The optional return value @var{h} is a vector of graphics handles to
+## the text objects representing each label.  
+## The "userdata" property of the text objects contains the numerical value of
+## the contour label.
 ##
 ## An example of the use of @code{clabel} is
 ##
@@ -128,12 +129,14 @@
   endif
 endfunction
 
-%!demo
-%! clf
-%! [c, h] = contour (peaks(), -4 : 6);
-%! clabel (c, h, -4 : 2 : 6, 'fontsize', 12);
 
 %!demo
 %! clf
-%! [c, h] = contourf (peaks(), -7 : 6);
-%! clabel (c, h, -6 : 2 : 6, 'fontsize', 12);
+%! [c, h] = contour (peaks(), -4:6);
+%! clabel (c, h, -4:2:6, "fontsize", 12);
+
+%!demo
+%! clf
+%! [c, h] = contourf (peaks(), -7:6);
+%! clabel (c, h, -6:2:6, "fontsize", 12);
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/clf.m
--- a/scripts/plot/clf.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/clf.m	Tue Dec 06 13:09:17 2011 -0800
@@ -26,8 +26,10 @@
 ## graphics objects with visible handles (@code{handlevisibility} = on).
 ## If @var{hfig} is specified operate on it instead of the current figure.
 ## If the optional argument @code{"reset"} is specified, all objects including
-## those with hidden handles are deleted.  If an output value is
-## requested, return the handle of the figure window that was cleared.
+## those with hidden handles are deleted.
+## 
+## The optional return value @var{h} is the graphics handle of the figure
+## window that was cleared.
 ## @seealso{cla, close, delete}
 ## @end deftypefn
 
@@ -82,6 +84,7 @@
 
 endfunction
 
+
 %!test
 %! hf = figure ("visible", "off");
 %! unwind_protect
@@ -99,3 +102,4 @@
 %! unwind_protect_cleanup
 %!   close (hf);
 %! end_unwind_protect
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/compass.m
--- a/scripts/plot/compass.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/compass.m	Tue Dec 06 13:09:17 2011 -0800
@@ -31,17 +31,17 @@
 ## The style to use for the plot can be defined with a line style @var{style}
 ## in a similar manner to the line styles used with the @code{plot} command.
 ##
-## The optional return value @var{h} provides a list of handles to the
-## the parts of the vector field (body, arrow and marker).
+## The optional return value @var{h} is a vector of graphics handles to the
+## line objects representing the drawn vectors.
 ##
 ## @example
 ## @group
-## a = toeplitz([1;randn(9,1)],[1,randn(1,9)]);
+## a = toeplitz ([1;randn(9,1)], [1,randn(1,9)]);
 ## compass (eig (a))
 ## @end group
 ## @end example
 ##
-## @seealso{plot, polar, quiver, feather}
+## @seealso{polar, quiver, feather, plot}
 ## @end deftypefn
 
 function retval = compass (varargin)
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/ezcontour.m
--- a/scripts/plot/ezcontour.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/ezcontour.m	Tue Dec 06 13:09:17 2011 -0800
@@ -35,8 +35,7 @@
 ##
 ## @var{n} is a scalar defining the number of points to use in each dimension.
 ##
-## The optional return value @var{h} provides a list of handles to the
-## the parts of the vector field (body, arrow and marker).
+## The optional return value @var{h} is a graphics handle to the created plot.
 ##
 ## @example
 ## @group
@@ -61,6 +60,8 @@
   endif
 endfunction
 
+
 %!demo
 %! f = @(x,y) sqrt(abs(x .* y)) ./ (1 + x.^2 + y.^2);
 %! ezcontour (f, [-3, 3]);
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/ezcontourf.m
--- a/scripts/plot/ezcontourf.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/ezcontourf.m	Tue Dec 06 13:09:17 2011 -0800
@@ -35,8 +35,7 @@
 ##
 ## @var{n} is a scalar defining the number of points to use in each dimension.
 ##
-## The optional return value @var{h} provides a list of handles to the
-## the parts of the vector field (body, arrow and marker).
+## The optional return value @var{h} is a graphics handle to the created plot.
 ##
 ## @example
 ## @group
@@ -61,6 +60,7 @@
   endif
 endfunction
 
+
 %!demo
 %! f = @(x,y) sqrt(abs(x .* y)) ./ (1 + x.^2 + y.^2);
 %! ezcontourf (f, [-3, 3]);
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/ezmesh.m
--- a/scripts/plot/ezmesh.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/ezmesh.m	Tue Dec 06 13:09:17 2011 -0800
@@ -44,8 +44,8 @@
 ## If the argument 'circ' is given, then the function is plotted over a disk
 ## centered on the middle of the domain @var{dom}.
 ##
-## The optional return value @var{h} provides a list of handles to the
-## the parts of the vector field (body, arrow and marker).
+## The optional return value @var{h} is a graphics handle to the created 
+## surface object.
 ##
 ## @example
 ## @group
@@ -65,7 +65,7 @@
 ## @end group
 ## @end example
 ##
-## @seealso{ezplot, ezsurf, ezsurfc, ezmeshc}
+## @seealso{ezplot, ezmeshc, ezsurf, ezsurfc}
 ## @end deftypefn
 
 function retval = ezmesh (varargin)
@@ -81,6 +81,7 @@
   endif
 endfunction
 
+
 %!demo
 %! f = @(x,y) sqrt(abs(x .* y)) ./ (1 + x.^2 + y.^2);
 %! ezmesh (f, [-3, 3]);
@@ -90,3 +91,4 @@
 %! fy = @(s,t) sin (s) .* cos(t);
 %! fz = @(s,t) sin (t);
 %! ezmesh (fx, fy, fz, [-pi,pi,-pi/2,pi/2], 20);
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/ezmeshc.m
--- a/scripts/plot/ezmeshc.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/ezmeshc.m	Tue Dec 06 13:09:17 2011 -0800
@@ -44,8 +44,9 @@
 ## If the argument 'circ' is given, then the function is plotted over a disk
 ## centered on the middle of the domain @var{dom}.
 ##
-## The optional return value @var{h} provides a list of handles to the
-## the parts of the vector field (body, arrow and marker).
+## The optional return value @var{h} is a 2-element vector with a graphics
+## handle for the created mesh plot and a second handle for the created contour
+## plot.
 ##
 ## @example
 ## @group
@@ -70,6 +71,8 @@
   endif
 endfunction
 
+
 %!demo
 %! f = @(x,y) sqrt(abs(x .* y)) ./ (1 + x.^2 + y.^2);
 %! ezmeshc (f, [-3, 3]);
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/ezplot.m
--- a/scripts/plot/ezplot.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/ezplot.m	Tue Dec 06 13:09:17 2011 -0800
@@ -61,8 +61,7 @@
 ## @var{n} is a scalar defining the number of points to use in plotting
 ## the function.
 ##
-## The optional return value @var{h} provides a list of handles to the
-## the line objects plotted.
+## The optional return value @var{h} is a graphics handle to the created plot.
 ##
 ## @seealso{plot, ezplot3}
 ## @end deftypefn
@@ -80,6 +79,7 @@
   endif
 endfunction
 
+
 %!demo
 %! ezplot (@cos, @sin)
 
@@ -87,4 +87,5 @@
 %! ezplot ("1/x")
 
 %!demo
-%! ezplot (inline("x^2 - y^2 = 1"))
+%! ezplot (inline ("x^2 - y^2 = 1"))
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/ezplot3.m
--- a/scripts/plot/ezplot3.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/ezplot3.m	Tue Dec 06 13:09:17 2011 -0800
@@ -32,8 +32,7 @@
 ## If @var{dom} is a two element vector, it represents the minimum and maximum
 ## value of @var{t}.  @var{n} is a scalar defining the number of points to use.
 ##
-## The optional return value @var{h} provides a list of handles to the
-## the parts of the vector field (body, arrow and marker).
+## The optional return value @var{h} is a graphics handle to the created plot.
 ##
 ## @example
 ## @group
@@ -60,8 +59,10 @@
   endif
 endfunction
 
+
 %!demo
 %! fx = @(t) cos (t);
 %! fy = @(t) sin (t);
 %! fz = @(t) t;
 %! ezplot3 (fx, fy, fz, [0, 10*pi], 100);
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/ezpolar.m
--- a/scripts/plot/ezpolar.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/ezpolar.m	Tue Dec 06 13:09:17 2011 -0800
@@ -32,8 +32,7 @@
 ## value of both @var{t}.  @var{n} is a scalar defining the number of points to
 ## use.
 ##
-## The optional return value @var{h} provides a list of handles to the
-## the parts of the vector field (body, arrow and marker).
+## The optional return value @var{h} is a graphics handle to the created plot.
 ##
 ## @example
 ## ezpolar (@@(t) 1 + sin (t));
@@ -55,5 +54,7 @@
   endif
 endfunction
 
+
 %!demo
 %! ezpolar (@(t) 1 + sin (t));
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/ezsurf.m
--- a/scripts/plot/ezsurf.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/ezsurf.m	Tue Dec 06 13:09:17 2011 -0800
@@ -44,8 +44,8 @@
 ## If the argument 'circ' is given, then the function is plotted over a disk
 ## centered on the middle of the domain @var{dom}.
 ##
-## The optional return value @var{h} provides a list of handles to the
-## the parts of the vector field (body, arrow and marker).
+## The optional return value @var{h} is a graphics handle to the created
+## surface object.
 ##
 ## @example
 ## @group
@@ -81,6 +81,7 @@
   endif
 endfunction
 
+
 %!demo
 %! f = @(x,y) sqrt(abs(x .* y)) ./ (1 + x.^2 + y.^2);
 %! ezsurf (f, [-3, 3]);
@@ -90,3 +91,4 @@
 %! fy = @(s,t) sin (s) .* cos(t);
 %! fz = @(s,t) sin (t);
 %! ezsurf (fx, fy, fz, [-pi,pi,-pi/2,pi/2], 20);
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/ezsurfc.m
--- a/scripts/plot/ezsurfc.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/ezsurfc.m	Tue Dec 06 13:09:17 2011 -0800
@@ -44,8 +44,9 @@
 ## If the argument 'circ' is given, then the function is plotted over a disk
 ## centered on the middle of the domain @var{dom}.
 ##
-## The optional return value @var{h} provides a list of handles to the
-## the parts of the vector field (body, arrow and marker).
+## The optional return value @var{h} is a 2-element vector with a graphics
+## for the created surface plot and a second handle for the created contour
+## plot.
 ##
 ## @example
 ## @group
@@ -70,6 +71,8 @@
   endif
 endfunction
 
+
 %!demo
 %! f = @(x,y) sqrt(abs(x .* y)) ./ (1 + x.^2 + y.^2);
 %! ezsurfc (f, [-3, 3]);
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/feather.m
--- a/scripts/plot/feather.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/feather.m	Tue Dec 06 13:09:17 2011 -0800
@@ -31,8 +31,8 @@
 ## The style to use for the plot can be defined with a line style @var{style}
 ## in a similar manner to the line styles used with the @code{plot} command.
 ##
-## The optional return value @var{h} provides a list of handles to the
-## the parts of the vector field (body, arrow and marker).
+## The optional return value @var{h} is a vector of graphics handles to the
+## line objects representing the drawn vectors.
 ##
 ## @example
 ## @group
@@ -109,6 +109,8 @@
 
 endfunction
 
+
 %!demo
 %! phi = [0 : 15 : 360] * pi / 180;
 %! feather (sin (phi), cos (phi))
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/fill.m
--- a/scripts/plot/fill.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/fill.m	Tue Dec 06 13:09:17 2011 -0800
@@ -22,7 +22,11 @@
 ## @deftypefnx {Function File} {} fill (@dots{}, @var{prop}, @var{val})
 ## @deftypefnx {Function File} {} fill (@var{h}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} fill (@dots{})
-## Create one or more filled patch objects, returning a patch object for each.
+## Create one or more filled patch objects.
+##
+## The optional return value @var{h} is an array of graphics handles to
+## the created patch objects.
+## @seealso{patch}
 ## @end deftypefn
 
 function retval = fill (varargin)
@@ -114,12 +118,14 @@
   endwhile
 endfunction
 
+
 %!demo
 %! clf
-%! t1 = (1/16:1/8:1)'*2*pi;
-%! t2 = ((1/16:1/8:1)' + 1/32)*2*pi;
-%! x1 = sin(t1) - 0.8;
-%! y1 = cos(t1);
-%! x2 = sin(t2) + 0.8;
-%! y2 = cos(t2);
-%! h = fill(x1,y1,'r',x2,y2,'g');
+%! t1 = (1/16:1/8:1)*2*pi;
+%! t2 = ((1/16:1/8:1) + 1/32)*2*pi;
+%! x1 = sin (t1) - 0.8;
+%! y1 = cos (t1);
+%! x2 = sin (t2) + 0.8;
+%! y2 = cos (t2);
+%! h = fill (x1,y1,'r', x2,y2,'g');
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/findall.m
--- a/scripts/plot/findall.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/findall.m	Tue Dec 06 13:09:17 2011 -0800
@@ -21,7 +21,7 @@
 ## @deftypefnx {Function File} {@var{h} =} findall (@var{prop_name}, @var{prop_value})
 ## @deftypefnx {Function File} {@var{h} =} findall (@var{h}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} findall (@var{h}, "-depth", @var{d}, @dots{})
-## Find object with specified property values including hidden handles.
+## Find graphics object with specified property values including hidden handles.
 ##
 ## This function performs the same function as @code{findobj}, but it
 ## includes hidden objects in its search.  For full documentation, see
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/findobj.m
--- a/scripts/plot/findobj.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/findobj.m	Tue Dec 06 13:09:17 2011 -0800
@@ -24,7 +24,7 @@
 ## @deftypefnx {Function File} {@var{h} =} findobj ('flat', @dots{})
 ## @deftypefnx {Function File} {@var{h} =} findobj (@var{h}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} findobj (@var{h}, '-depth', @var{d}, @dots{})
-## Find object with specified property values.  The simplest form is
+## Find graphics object with specified property values.  The simplest form is
 ##
 ## @example
 ## findobj (@var{prop_name}, @var{prop_Value})
@@ -243,6 +243,7 @@
   h = reshape (h, [numel(h), 1]);
 endfunction
 
+
 %!test
 %! hf = figure ("visible", "off");
 %! unwind_protect
@@ -255,3 +256,4 @@
 %! unwind_protect_cleanup
 %!   close (hf);
 %! end_unwind_protect
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/loglog.m
--- a/scripts/plot/loglog.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/loglog.m	Tue Dec 06 13:09:17 2011 -0800
@@ -26,6 +26,8 @@
 ## Produce a two-dimensional plot using log scales for both axes.  See
 ## the documentation of @code{plot} for a description of the arguments
 ## that @code{loglog} will accept.
+##
+## The optional return value @var{h} is a graphics handle to the created plot.
 ## @seealso{plot, semilogx, semilogy}
 ## @end deftypefn
 
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/mesh.m
--- a/scripts/plot/mesh.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/mesh.m	Tue Dec 06 13:09:17 2011 -0800
@@ -32,6 +32,9 @@
 ## The color of the mesh is derived from the @code{colormap}
 ## and the value of @var{z}.  Optionally the color of the mesh can be
 ## specified independent of @var{z}, by adding a fourth matrix, @var{c}.
+##
+## The optional return value @var{h} is a graphics handle to the created
+## suface object.
 ## @seealso{colormap, contour, meshgrid, surf}
 ## @end deftypefn
 
@@ -58,3 +61,7 @@
   endif
 
 endfunction
+
+
+%% FIXME: Need demo or test for function
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/pareto.m
--- a/scripts/plot/pareto.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/pareto.m	Tue Dec 06 13:09:17 2011 -0800
@@ -41,6 +41,10 @@
 ## @var{y} can be a string array, a cell array of strings or a numerical
 ## vector.
 ##
+## The optional return value @var{h} is a 2-element vector with a graphics
+## handle for the created bar plot and a second handle for the created line
+## plot.
+##
 ## An example of the use of @code{pareto} is
 ##
 ## @example
@@ -48,7 +52,7 @@
 ## Cheese = @{"Cheddar", "Swiss", "Camembert", ...
 ##           "Munster", "Stilton", "Blue"@};
 ## Sold = [105, 30, 70, 10, 15, 20];
-## pareto(Sold, Cheese);
+## pareto (Sold, Cheese);
 ## @end group
 ## @end example
 ## @end deftypefn
@@ -99,12 +103,13 @@
 
 endfunction
 
+
 %!demo
 %! clf
-%! colormap (jet (64))
+%! colormap (jet (64));
 %! Cheese = {"Cheddar", "Swiss", "Camembert", "Munster", "Stilton", "Blue"};
 %! Sold = [105, 30, 70, 10, 15, 20];
-%! pareto(Sold, Cheese);
+%! pareto (Sold, Cheese);
 
 %!demo
 %! clf
@@ -114,3 +119,4 @@
 %! SoldUnits = [54723 41114 16939 1576091 168000 687197 120222 168195, ...
 %!              1084118 55576]';
 %! pareto (Value.*SoldUnits, Codes);
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/patch.m
--- a/scripts/plot/patch.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/patch.m	Tue Dec 06 13:09:17 2011 -0800
@@ -35,6 +35,10 @@
 ## If passed a structure @var{fv} contain the fields "vertices", "faces"
 ## and optionally "facevertexcdata", create the patch based on these
 ## properties.
+##
+## The optional return value @var{h} is a graphics handle to the created patch
+## object.
+## @seealso{fill}
 ## @end deftypefn
 
 ## Author: jwe
@@ -60,10 +64,10 @@
 %! clf
 %! t1 = (1/16:1/8:1)'*2*pi;
 %! t2 = ((1/16:1/8:1)' + 1/32)*2*pi;
-%! x1 = sin(t1) - 0.8;
-%! y1 = cos(t1);
-%! x2 = sin(t2) + 0.8;
-%! y2 = cos(t2);
+%! x1 = sin (t1) - 0.8;
+%! y1 = cos (t1);
+%! x2 = sin (t2) + 0.8;
+%! y2 = cos (t2);
 %! patch([x1,x2],[y1,y2],'r');
 
 %!demo
@@ -71,10 +75,10 @@
 %! clf
 %! t1 = (1/16:1/8:1)'*2*pi;
 %! t2 = ((1/16:1/16:1)' + 1/32)*2*pi;
-%! x1 = sin(t1) - 0.8;
-%! y1 = cos(t1);
-%! x2 = sin(t2) + 0.8;
-%! y2 = cos(t2);
+%! x1 = sin (t1) - 0.8;
+%! y1 = cos (t1);
+%! x2 = sin (t2) + 0.8;
+%! y2 = cos (t2);
 %! patch([[x1;NaN(8,1)],x2],[[y1;NaN(8,1)],y2],'r');
 
 %!demo
@@ -82,10 +86,10 @@
 %! clf
 %! t1 = (1/16:1/8:1)'*2*pi;
 %! t2 = ((1/16:1/16:1)' + 1/32)*2*pi;
-%! x1 = sin(t1) - 0.8;
-%! y1 = cos(t1);
-%! x2 = sin(t2) + 0.8;
-%! y2 = cos(t2);
+%! x1 = sin (t1) - 0.8;
+%! y1 = cos (t1);
+%! x2 = sin (t2) + 0.8;
+%! y2 = cos (t2);
 %! vert = [x1, y1; x2, y2];
 %! fac = [1:8,NaN(1,8);9:24];
 %! patch('Faces',fac,'Vertices',vert,'FaceColor','r');
@@ -95,10 +99,10 @@
 %! clf
 %! t1 = (1/16:1/8:1)'*2*pi;
 %! t2 = ((1/16:1/16:1)' + 1/32)*2*pi;
-%! x1 = sin(t1) - 0.8;
-%! y1 = cos(t1);
-%! x2 = sin(t2) + 0.8;
-%! y2 = cos(t2);
+%! x1 = sin (t1) - 0.8;
+%! y1 = cos (t1);
+%! x2 = sin (t2) + 0.8;
+%! y2 = cos (t2);
 %! vert = [x1, y1; x2, y2];
 %! fac = [1:8,NaN(1,8);9:24];
 %! patch('Faces',fac,'Vertices',vert,'FaceVertexCData', [0, 1, 0; 0, 0, 1]);
@@ -108,10 +112,10 @@
 %! clf
 %! t1 = (1/16:1/8:1)'*2*pi;
 %! t2 = ((1/16:1/8:1)' + 1/32)*2*pi;
-%! x1 = sin(t1) - 0.8;
-%! y1 = cos(t1);
-%! x2 = sin(t2) + 0.8;
-%! y2 = cos(t2);
+%! x1 = sin (t1) - 0.8;
+%! y1 = cos (t1);
+%! x2 = sin (t2) + 0.8;
+%! y2 = cos (t2);
 %! h = patch([x1,x2],[y1,y2],cat (3,[0,0],[1,0],[0,1]));
 %! pause (1);
 %! set (h, 'FaceColor', 'r');
@@ -127,9 +131,9 @@
 %!          2, 3, 5;
 %!          3, 4, 5;
 %!          4, 1, 5];
-%! patch('Vertices', vertices, 'Faces', faces, ...
-%!       'FaceVertexCData', jet(4), 'FaceColor', 'flat')
-%! view (-37.5, 30)
+%! patch ('Vertices', vertices, 'Faces', faces, ...
+%!        'FaceVertexCData', jet(4), 'FaceColor', 'flat');
+%! view (-37.5, 30);
 
 %!demo
 %! clf
@@ -142,37 +146,37 @@
 %!          2, 3, 5;
 %!          3, 4, 5;
 %!          4, 1, 5];
-%! patch('Vertices', vertices, 'Faces', faces, ...
-%!       'FaceVertexCData', jet(5), 'FaceColor', 'interp')
-%! view (-37.5, 30)
+%! patch ('Vertices', vertices, 'Faces', faces, ...
+%!        'FaceVertexCData', jet(5), 'FaceColor', 'interp');
+%! view (-37.5, 30);
 
 %!demo
 %! clf
-%! colormap (jet)
+%! colormap (jet);
 %! x = [0 1 1 0];
 %! y = [0 0 1 1];
-%! subplot (2, 1, 1)
-%! title ("Blue, Light-Green, and Red Horizontal Bars")
+%! subplot (2, 1, 1);
+%! title ("Blue, Light-Green, and Red Horizontal Bars");
 %! patch (x, y + 0, 1);
 %! patch (x, y + 1, 2);
 %! patch (x, y + 2, 3);
-%! subplot (2, 1, 2)
-%! title ("Blue, Light-Green, and Red Vertical Bars")
+%! subplot (2, 1, 2);
+%! title ("Blue, Light-Green, and Red Vertical Bars");
 %! patch (x + 0, y, 1 * ones (size (x)));
 %! patch (x + 1, y, 2 * ones (size (x)));
 %! patch (x + 2, y, 3 * ones (size (x)));
 
 %!demo
 %! clf
-%! colormap (jet)
+%! colormap (jet);
 %! x = [0 1 1 0];
 %! y = [0 0 1 1];
-%! subplot (2, 1, 1)
-%! title ("Blue horizontal bars: Dark to Light")
+%! subplot (2, 1, 1);
+%! title ("Blue horizontal bars: Dark to Light");
 %! patch (x, y + 0, 1, "cdatamapping", "direct");
 %! patch (x, y + 1, 9, "cdatamapping", "direct");
 %! patch (x, y + 2, 17, "cdatamapping", "direct");
-%! subplot (2, 1, 2)
+%! subplot (2, 1, 2);
 %! title ("Blue vertical bars: Dark to Light")
 %! patch (x + 0, y, 1 * ones (size (x)), "cdatamapping", "direct");
 %! patch (x + 1, y, 9 * ones (size (x)), "cdatamapping", "direct");
@@ -184,9 +188,9 @@
 %! x = [ 0 0; 1 1; 1 0 ];
 %! y = [ 0 0; 0 1; 1 1 ];
 %! p = patch (x, y, "facecolor", "b");
-%! title ("Two blue triangles")
-%! set (p, "cdatamapping", "direct", "facecolor", "flat", "cdata", [1 32])
-%! title ("Direct mapping of colors: Light-Green UL and Blue LR triangles")
+%! title ("Two blue triangles");
+%! set (p, "cdatamapping", "direct", "facecolor", "flat", "cdata", [1 32]);
+%! title ("Direct mapping of colors: Light-Green UL and Blue LR triangles");
 
 %!demo
 %! clf;
@@ -194,7 +198,7 @@
 %! x = [ 0 0; 1 1; 1 0 ];
 %! y = [ 0 0; 0 1; 1 1 ];
 %! p = patch (x, y, [1 32]);
-%! title ("Autoscaling of colors: Red UL and Blue LR triangles")
+%! title ("Autoscaling of colors: Red UL and Blue LR triangles");
 
 %!test
 %! hf = figure ("visible", "off");
@@ -203,8 +207,8 @@
 %!   assert (findobj (hf, "type", "patch"), h);
 %!   assert (get (h, "xdata"), [0; 1; 0], eps);
 %!   assert (get (h, "ydata"), [1; 1; 0], eps);
-%!   assert (isempty(get (h, "zdata")));
-%!   assert (isempty(get (h, "cdata")));
+%!   assert (isempty (get (h, "zdata")));
+%!   assert (isempty (get (h, "cdata")));
 %!   assert (get (h, "faces"), [1, 2, 3], eps);
 %!   assert (get (h, "vertices"), [0 1; 1 1; 0 0], eps);
 %!   assert (get (h, "type"), "patch");
@@ -228,3 +232,4 @@
 %! unwind_protect_cleanup
 %!   close (hf);
 %! end_unwind_protect
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/pie.m
--- a/scripts/plot/pie.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/pie.m	Tue Dec 06 13:09:17 2011 -0800
@@ -22,7 +22,7 @@
 ## @deftypefnx {Function File} {} pie (@dots{}, @var{labels})
 ## @deftypefnx {Function File} {} pie (@var{h}, @dots{});
 ## @deftypefnx {Function File} {@var{h} =} pie (@dots{});
-## Produce a pie chart.
+## Produce a 2-D pie chart.
 ##
 ## Called with a single vector argument, produces a pie chart of the
 ## elements in @var{x}, with the size of the slice determined by percentage
@@ -34,7 +34,8 @@
 ## If given @var{labels} is a cell array of strings of the same length as
 ## @var{x}, giving the labels of each of the slices of the pie chart.
 ##
-## The optional return value @var{h} provides a handle to the patch object.
+## The optional return value @var{h} is a list of handles to the patch
+## and text objects generating the plot.
 ##
 ## @seealso{pie3, bar, stem}
 ## @end deftypefn
@@ -65,17 +66,19 @@
 
 endfunction
 
+
 %!demo
 %! pie ([3, 2, 1], [0, 0, 1]);
-%! colormap([1,0,0;0,1,0;0,0,1;1,1,0;1,0,1;0,1,1]);
+%! colormap ([1,0,0;0,1,0;0,0,1;1,1,0;1,0,1;0,1,1]);
 
 %!demo
 %! pie ([3, 2, 1], [0, 0, 1], {"Cheddar", "Swiss", "Camembert"});
-%! colormap([1,0,0;0,1,0;0,0,1;1,1,0;1,0,1;0,1,1]);
+%! colormap ([1,0,0;0,1,0;0,0,1;1,1,0;1,0,1;0,1,1]);
 %! axis ([-2,2,-2,2]);
 
 %!demo
 %! pie ([0.17, 0.34, 0.41], {"Cheddar", "Swiss", "Camembert"});
-%! colormap([1,0,0;0,1,0;0,0,1;1,1,0;1,0,1;0,1,1]);
+%! colormap ([1,0,0;0,1,0;0,0,1;1,1,0;1,0,1;0,1,1]);
 %! axis ([-2,2,-2,2]);
-%! title ("missing slice");
\ No newline at end of file
+%! title ("missing slice");
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/pie3.m
--- a/scripts/plot/pie3.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/pie3.m	Tue Dec 06 13:09:17 2011 -0800
@@ -35,8 +35,8 @@
 ## If given @var{labels} is a cell array of strings of the same length as
 ## @var{x}, giving the labels of each of the slices of the pie chart.
 ##
-## The optional return value @var{h} provides a handle list to patch, surface
-## and text objects generating this plot.
+## The optional return value @var{h} is a list of graphics handles to the patch,
+## surface, and text objects generating the plot.
 ##
 ## @seealso{pie, bar, stem}
 ## @end deftypefn
@@ -67,17 +67,19 @@
 
 endfunction
 
+
 %!demo
 %! pie3 ([5:-1:1], [0, 0, 1, 0, 0]);
-%! colormap([1,0,0;0,1,0;0,0,1;1,1,0;1,0,1;0,1,1]);
+%! colormap ([1,0,0;0,1,0;0,0,1;1,1,0;1,0,1;0,1,1]);
 
 %!demo
 %! pie3 ([3, 2, 1], [0, 0, 1], {"Cheddar", "Swiss", "Camembert"});
-%! colormap([1,0,0;0,1,0;0,0,1;1,1,0;1,0,1;0,1,1]);
+%! colormap ([1,0,0;0,1,0;0,0,1;1,1,0;1,0,1;0,1,1]);
 %! axis ([-2,2,-2,2]);
 
 %!demo
 %! pie3 ([0.17, 0.34, 0.41], {"Cheddar", "Swiss", "Camembert"});
-%! colormap([1,0,0;0,1,0;0,0,1;1,1,0;1,0,1;0,1,1]);
+%! colormap ([1,0,0;0,1,0;0,0,1;1,1,0;1,0,1;0,1,1]);
 %! axis ([-2,2,-2,2]);
 %! title ("missing slice");
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/plot.m
--- a/scripts/plot/plot.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/plot.m	Tue Dec 06 13:09:17 2011 -0800
@@ -173,6 +173,8 @@
 ## If the first argument is an axis handle, then plot into these axes,
 ## rather than the current axis handle returned by @code{gca}.
 ##
+## The optional return value @var{h} is a graphics handle to the created plot.
+##
 ## @seealso{semilogx, semilogy, loglog, polar, mesh, contour, bar,
 ## stairs, errorbar, xlabel, ylabel, title, print}
 ## @end deftypefn
@@ -201,3 +203,7 @@
   endif
 
 endfunction
+
+
+%% FIXME: Need demo or test for function
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/polar.m
--- a/scripts/plot/polar.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/polar.m	Tue Dec 06 13:09:17 2011 -0800
@@ -21,10 +21,13 @@
 ## @deftypefnx {Function File} {} polar (@var{theta}, @var{rho}, @var{fmt})
 ## @deftypefnx {Function File} {} polar (@var{h}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} polar (@dots{})
-## Make a two-dimensional plot given the polar coordinates @var{theta} and
+## Create a two-dimensional plot from polar coordinates @var{theta} and
 ## @var{rho}.
 ##
-## The optional third argument specifies the line type.
+## The optional argument @var{fmt} specifies the line format.
+##
+## The optional return value @var{h} is a graphics handle to the created plot.
+##
 ## @seealso{plot}
 ## @end deftypefn
 
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/quiver.m
--- a/scripts/plot/quiver.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/quiver.m	Tue Dec 06 13:09:17 2011 -0800
@@ -34,7 +34,7 @@
 ## size(@var{u})}.
 ##
 ## The variable @var{s} is a scalar defining a scaling factor to use for
-##  the arrows of the field relative to the mesh spacing.  A value of 0
+## the arrows of the field relative to the mesh spacing.  A value of 0
 ## disables all scaling.  The default value is 1.
 ##
 ## The style to use for the plot can be defined with a line style @var{style}
@@ -43,9 +43,9 @@
 ## printed rather than arrows.  If the argument 'filled' is given then the
 ## markers as filled.
 ##
-## The optional return value @var{h} provides a quiver group that
-## regroups the components of the quiver plot (body, arrow and marker),
-## and allows them to be changed together
+## The optional return value @var{h} is a graphics handle to a quiver object.
+## A quiver object regroups the components of the quiver plot (body, arrow,
+## and marker), and allows them to be changed together.
 ##
 ## @example
 ## @group
@@ -81,14 +81,18 @@
 
 endfunction
 
+
 %!demo
 %! clf
-%! [x,y] = meshgrid(1:2:20);
-%! h = quiver(x,y,sin(2*pi*x/10),sin(2*pi*y/10));
+%! [x,y] = meshgrid (1:2:20);
+%! h = quiver (x,y, sin (2*pi*x/10), sin (2*pi*y/10));
 %! set (h, "maxheadsize", 0.33);
 
 %!demo
-%! axis("equal");
-%! x=linspace(0,3,80); y=sin(2*pi*x); theta=2*pi*x+pi/2;
-%! quiver(x,y,sin(theta)/10,cos(theta)/10);
+%! axis ("equal");
+%! x = linspace (0,3,80);
+%! y = sin (2*pi*x);
+%! theta = 2*pi*x + pi/2;
+%! quiver (x, y, sin (theta)/10, cos (theta)/10);
 %! hold on; plot(x,y,"r"); hold off;
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/quiver3.m
--- a/scripts/plot/quiver3.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/quiver3.m	Tue Dec 06 13:09:17 2011 -0800
@@ -43,9 +43,9 @@
 ## printed rather than arrows.  If the argument 'filled' is given then the
 ## markers as filled.
 ##
-## The optional return value @var{h} provides a quiver group that
-## regroups the components of the quiver plot (body, arrow and marker),
-## and allows them to be changed together
+## The optional return value @var{h} is a graphics handle to a quiver object.
+## A quiver object regroups the components of the quiver plot (body, arrow,
+## and marker), and allows them to be changed together.
 ##
 ## @example
 ## @group
@@ -86,13 +86,13 @@
 
 %!demo
 %! clf
-%! colormap (jet (64))
-%! [x,y]=meshgrid (-1:0.1:1);
-%! z=sin(2*pi*sqrt(x.^2+y.^2));
-%! theta=2*pi*sqrt(x.^2+y.^2)+pi/2;
-%! quiver3(x,y,z,sin(theta),cos(theta),ones(size(z)));
+%! colormap (jet (64));
+%! [x,y] = meshgrid (-1:0.1:1);
+%! z = sin (2*pi * sqrt (x.^2+y.^2));
+%! theta = 2*pi * sqrt (x.^2+y.^2) + pi/2;
+%! quiver3 (x, y, z, sin (theta), cos (theta), ones (size (z)));
 %! hold on;
-%! mesh(x,y,z);
+%! mesh (x,y,z);
 %! hold off;
 
 %!demo
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/rectangle.m
--- a/scripts/plot/rectangle.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/rectangle.m	Tue Dec 06 13:09:17 2011 -0800
@@ -44,9 +44,10 @@
 ## min (pos (1:2)) / max (pos (1:2)) * curv
 ## @end example
 ##
-## Other properties are passed to the underlying patch command.  If called
-## with an output argument, @code{rectangle} returns the handle to the
-## rectangle.
+## Other properties are passed to the underlying patch command. 
+## 
+## The optional return value @var{h} is a graphics handle to the created
+## rectangle object.
 ## @end deftypefn
 ## @seealso{patch}
 
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/ribbon.m
--- a/scripts/plot/ribbon.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/ribbon.m	Tue Dec 06 13:09:17 2011 -0800
@@ -23,9 +23,10 @@
 ## Plot a ribbon plot for the columns of @var{y} vs.  @var{x}.  The
 ## optional parameter @var{width} specifies the width of a single ribbon
 ## (default is 0.75).  If @var{x} is omitted, a vector containing the
-## row numbers is assumed (1:rows(Y)).  If requested, return a vector
-## @var{h} of the handles to the surface objects.
-## @seealso{gca, colorbar}
+## row numbers is assumed (1:rows(Y)).
+##
+## The optional return value @var{h} is a vector of graphics handles to
+## the surface objects representing each ribbon.
 ## @end deftypefn
 
 ## Author: Kai Habel <kai.habel at gmx.de>
@@ -85,7 +86,9 @@
 
 endfunction
 
+
 %!demo
 %! [x, y, z] = sombrero ();
 %! [x, y] = meshgrid (x, y);
 %! ribbon (y, z);
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/rose.m
--- a/scripts/plot/rose.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/rose.m	Tue Dec 06 13:09:17 2011 -0800
@@ -30,10 +30,10 @@
 ## @var{r} bins.  If @var{r} is a vector, then the center of each bin are
 ## defined by the values of @var{r}.
 ##
-## The optional return value @var{h} provides a list of handles to the
-## the parts of the vector field (body, arrow and marker).
+## The optional return value @var{h} is a vector of graphics handles to the
+## line objects representing each histogram.
 ##
-## If two output arguments are requested, then rather than plotting the
+## If two output arguments are requested then, rather than plotting the
 ## histogram, the polar vectors necessary to plot the histogram are
 ## returned.
 ##
@@ -44,8 +44,7 @@
 ## @end group
 ## @end example
 ##
-##
-## @seealso{plot, compass, polar, hist}
+## @seealso{polar, compass, hist}
 ## @end deftypefn
 
 function [thout, rout] = rose (varargin)
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/scatter.m
--- a/scripts/plot/scatter.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/scatter.m	Tue Dec 06 13:09:17 2011 -0800
@@ -44,7 +44,8 @@
 ## If the argument @code{"filled"} is given then the markers as filled.  All
 ## additional arguments are passed to the underlying patch command.
 ##
-## The optional return value @var{h} provides a handle to the patch object
+## The optional return value @var{h} is a graphics handle to the hggroup
+## object representing the points.
 ##
 ## @example
 ## @group
@@ -89,7 +90,7 @@
 %!demo
 %! x = randn (100, 1);
 %! y = randn (100, 1);
-%! scatter (x, y, [], sqrt(x.^2 + y.^2));
+%! scatter (x, y, [], sqrt (x.^2 + y.^2));
 
 %!demo
 %! rand_10x1_data1 = [0.171577, 0.404796, 0.025469, 0.335309, 0.047814, 0.898480, 0.639599, 0.700247, 0.497798, 0.737940];
@@ -117,8 +118,9 @@
 
 %!demo
 %! n = 500;
-%! x = rand(n,1);
-%! y = rand(n,1);
-%! idx = ceil(rand(n,1)*3);
+%! x = rand (n,1);
+%! y = rand (n,1);
+%! idx = ceil (rand (n,1)*3);
 %! colors = eye(3)(idx, :);
-%! scatter(x,y,15, colors, "filled")
\ No newline at end of file
+%! scatter (x,y,15, colors, "filled");
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/scatter3.m
--- a/scripts/plot/scatter3.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/scatter3.m	Tue Dec 06 13:09:17 2011 -0800
@@ -41,7 +41,8 @@
 ## If the argument 'filled' is given then the markers as filled.  All
 ## additional arguments are passed to the underlying patch command.
 ##
-## The optional return value @var{h} provides a handle to the patch object
+## The optional return value @var{h} is a graphics handle to the hggroup
+## object representing the points.
 ##
 ## @example
 ## @group
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/semilogx.m
--- a/scripts/plot/semilogx.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/semilogx.m	Tue Dec 06 13:09:17 2011 -0800
@@ -26,6 +26,8 @@
 ## Produce a two-dimensional plot using a logarithmic scale for the @var{x}
 ## axis.  See the documentation of @code{plot} for a description of the
 ## arguments that @code{semilogx} will accept.
+## 
+## The optional return value @var{h} is a graphics handle to the created plot.
 ## @seealso{plot, semilogy, loglog}
 ## @end deftypefn
 
@@ -60,6 +62,7 @@
 
 endfunction
 
+
 %!demo
 %! x = 1:0.01:10;
 %! y = (x .* (1 + rand (size (x)))) .^ 2;
@@ -70,28 +73,28 @@
 %! x = logspace (-5, 1, 10);
 %! y = logspace (-5, 1, 10);
 %!
-%! subplot (1, 2, 1)
-%! semilogx (x, y)
-%! xlabel ('semilogx (x, y)')
+%! subplot (1, 2, 1);
+%! semilogx (x, y);
+%! xlabel ("semilogx (x, y)");
 %!
-%! subplot (1, 2, 2)
-%! semilogx (-x, y)
-%! xlabel ('semilogx (-x, y)')
+%! subplot (1, 2, 2);
+%! semilogx (-x, y);
+%! xlabel ("semilogx (-x, y)");
 
 %!demo
 %! clf ();
 %! x = logspace (-5, 1, 10);
 %! y = logspace (-5, 1, 10);
 %!
-%! subplot (1, 2, 1)
-%! semilogx (x, y)
+%! subplot (1, 2, 1);
+%! semilogx (x, y);
 %! set (gca, "xdir", "reverse", "activepositionproperty", "outerposition")
 %! xlabel ({"semilogx (x, y)", "xdir = reversed"})
 %!
-%! subplot (1, 2, 2)
-%! semilogx (-x, y)
-%! set (gca, "xdir", "reverse", "activepositionproperty", "outerposition")
-%! xlabel ({"semilogx (-x, y)","xdir = reversed"})
+%! subplot (1, 2, 2);
+%! semilogx (-x, y);
+%! set (gca, "xdir", "reverse", "activepositionproperty", "outerposition");
+%! xlabel ({"semilogx (-x, y)", "xdir = reversed"});
 
 %!test
 %! hf = figure ("visible", "off");
@@ -102,7 +105,7 @@
 %!   assert (get (gca, "xscale"), "log");
 %!   assert (get (gca, "yscale"), "linear");
 %! unwind_protect_cleanup
-%! close (hf);
+%!   close (hf);
 %! end_unwind_protect
 
 %!test
@@ -110,9 +113,10 @@
 %! unwind_protect
 %!   a = logspace (-5, 1, 10);
 %!   b =-logspace (-5, 1, 10);
-%!   semilogx (a, b)
-%!   axis tight
+%!   semilogx (a, b);
+%!   axis tight;
 %!   assert (all (get (gca, "ytick") < 0));
 %! unwind_protect_cleanup
-%! close (hf);
+%!   close (hf);
 %! end_unwind_protect
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/semilogy.m
--- a/scripts/plot/semilogy.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/semilogy.m	Tue Dec 06 13:09:17 2011 -0800
@@ -26,6 +26,8 @@
 ## Produce a two-dimensional plot using a logarithmic scale for the @var{y}
 ## axis.  See the documentation of @code{plot} for a description of the
 ## arguments that @code{semilogy} will accept.
+##
+## The optional return value @var{h} is a graphics handle to the created plot.
 ## @seealso{plot, semilogx, loglog}
 ## @end deftypefn
 
@@ -71,39 +73,39 @@
 %! x = logspace (-5, 1, 10);
 %! y = logspace (-5, 1, 10);
 %!
-%! subplot (2, 1, 1)
-%! semilogy (x, y)
-%! ylabel ('semilogy (x, y)')
+%! subplot (2, 1, 1);
+%! semilogy (x, y);
+%! ylabel ("semilogy (x, y)");
 %!
-%! subplot (2, 1, 2)
-%! semilogy (x, -y)
-%! ylabel ('semilogy (x, -y)')
+%! subplot (2, 1, 2);
+%! semilogy (x, -y);
+%! ylabel ("semilogy (x, -y)");
 
 %!demo
 %! clf ();
 %! x = logspace (-5, 1, 10);
 %! y = logspace (-5, 1, 10);
 %!
-%! subplot (2, 1, 1)
-%! semilogy (x, y)
-%! set (gca, "ydir", "reverse", "activepositionproperty", "outerposition")
-%! ylabel ({"semilogy (x, y)", "ydir = reversed"})
+%! subplot (2, 1, 1);
+%! semilogy (x, y);
+%! set (gca, "ydir", "reverse", "activepositionproperty", "outerposition");
+%! ylabel ({"semilogy (x, y)", "ydir = reversed"});
 %!
-%! subplot (2, 1, 2)
-%! semilogy (x, -y)
-%! set (gca, "ydir", "reverse", "activepositionproperty", "outerposition")
-%! ylabel ({"semilogy (x, -y)", "ydir = reversed"})
+%! subplot (2, 1, 2);
+%! semilogy (x, -y);
+%! set (gca, "ydir", "reverse", "activepositionproperty", "outerposition");
+%! ylabel ({"semilogy (x, -y)", "ydir = reversed"});
 
 %!test
 %! hf = figure ("visible", "off");
 %! unwind_protect
 %!   a = logspace (-5, 1, 10);
 %!   b = logspace (-5, 1, 10);
-%!   semilogy (a, b)
+%!   semilogy (a, b);
 %!   assert (get (gca, "yscale"), "log");
 %!   assert (get (gca, "xscale"), "linear");
 %! unwind_protect_cleanup
-%! close (hf);
+%!   close (hf);
 %! end_unwind_protect
 
 %!test
@@ -111,11 +113,10 @@
 %! unwind_protect
 %!   a = logspace (-5, 1, 10);
 %!   b =-logspace (-5, 1, 10);
-%!   semilogy (a, b)
-%!   axis tight
+%!   semilogy (a, b);
+%!   axis tight;
 %!   assert (all (get (gca, "ytick") < 0));
 %! unwind_protect_cleanup
-%! close (hf);
+%!   close (hf);
 %! end_unwind_protect
 
-
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/slice.m
--- a/scripts/plot/slice.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/slice.m	Tue Dec 06 13:09:17 2011 -0800
@@ -55,8 +55,9 @@
 ## @end table
 ##
 ## The default method is @code{"linear"}.
-## The optional return value @var{h} is a vector of handles to the
-## surface graphic objects.
+##
+## The optional return value @var{h} is a graphics handle to the created
+## surface object.
 ##
 ## Examples:
 ##
@@ -179,10 +180,14 @@
 
 endfunction
 
+
 %!demo
 %! [x, y, z] = meshgrid (linspace (-8, 8, 32));
 %! v = sin (sqrt (x.^2 + y.^2 + z.^2)) ./ (sqrt (x.^2 + y.^2 + z.^2));
 %! slice (x, y, z, v, [], 0, []);
+
+%!demo
 %! [xi, yi] = meshgrid (linspace (-7, 7));
 %! zi = xi + yi;
 %! slice (x, y, z, v, xi, yi, zi);
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/stem.m
--- a/scripts/plot/stem.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/stem.m	Tue Dec 06 13:09:17 2011 -0800
@@ -47,8 +47,8 @@
 ## @noindent
 ## plots 10 stems with heights from 2 to 20 in red;
 ##
-## The return value of @code{stem} is a vector of "stem series" graphics
-## handles, with one handle per column of the variable @var{y}.  This
+## The optional return value @var{h} is a vector of "stem series" graphics
+## handles with one handle per column of the variable @var{y}.  The
 ## handle regroups the elements of the stem graph together as the
 ## children of the "stem series" handle, allowing them to be altered
 ## together.  For example,
@@ -86,33 +86,34 @@
 
 endfunction
 
+
 %!demo
 %! x = 1:10;
 %! stem (x);
 
 %!demo
 %! x = 1:10;
-%! y = ones (1, length (x))*2.*x;
+%! y = 2*x;
 %! stem (x, y);
 
 %!demo
 %! x = 1:10;
-%! y = ones (size (x))*2.*x;
+%! y = 2*x;
 %! h = stem (x, y, "r");
 
 %!demo
 %! x = 1:10;
-%! y = ones (size (x))*2.*x;
+%! y = 2*x;
 %! h = stem (x, y, "-.k");
 
 %!demo
 %! x = 1:10;
-%! y = ones (size (x))*2.*x;
+%! y = 2*x;
 %! h = stem (x, y, "-.k.");
 
 %!demo
 %! x = 1:10;
-%! y = ones (size (x))*2.*x;
+%! y = 2*x;
 %! h = stem (x, y, "filled");
 
 %!demo
@@ -121,3 +122,4 @@
 %! h = stem (x, y);
 %! set (h(2), "color", "g");
 %! set (h(1), "basevalue", -1)
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/surf.m
--- a/scripts/plot/surf.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/surf.m	Tue Dec 06 13:09:17 2011 -0800
@@ -32,6 +32,9 @@
 ## The color of the surface is derived from the @code{colormap} and
 ## the value of @var{z}.  Optionally the color of the surface can be
 ## specified independent of @var{z}, by adding a fourth matrix, @var{c}.
+##
+## The optional return value @var{h} is a graphics handle to the created
+## surface object.
 ## @seealso{colormap, contour, meshgrid, mesh}
 ## @end deftypefn
 
@@ -61,19 +64,21 @@
 
 endfunction
 
+
 %!demo
 %! clf
-%! [~,~,Z]=peaks;
-%! surf(Z);
+%! [~,~,Z] = peaks;
+%! surf (Z);
 
 %!demo
-%! [~,~,Z]=sombrero;
-%! [Fx,Fy] = gradient(Z);
-%! surf(Z,Fx+Fy);
+%! [~,~,Z] = sombrero;
+%! [Fx,Fy] = gradient (Z);
+%! surf (Z, Fx+Fy);
 %! shading interp;
 
 %!demo
-%! [X,Y,Z]=sombrero;
-%! [~,Fy] = gradient(Z);
-%! surf(X,Y,Z,Fy);
+%! [X,Y,Z] = sombrero;
+%! [~,Fy] = gradient (Z);
+%! surf (X, Y, Z, Fy);
 %! shading interp;
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/surface.m
--- a/scripts/plot/surface.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/surface.m	Tue Dec 06 13:09:17 2011 -0800
@@ -33,6 +33,9 @@
 ## are missing, they are constructed from size of the matrix @var{z}.
 ##
 ## Any additional properties passed are assigned to the surface.
+## 
+## The optional return value @var{h} is a graphics handle to the created
+## surface object.
 ## @seealso{surf, mesh, patch, line}
 ## @end deftypefn
 
@@ -163,8 +166,7 @@
 
 endfunction
 
-## Mark file as being tested.  Tests for surface are in
-## surf.m, surfc.m, surfl.m, and pcolor.m
+## Functional tests for surface() are in surf.m, surfc.m, surfl.m, and pcolor.m
 
 %!test
 %! hf = figure ("visible", "off");
@@ -183,3 +185,4 @@
 %! unwind_protect_cleanup
 %!   close (hf);
 %! end_unwind_protect
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/text.m
--- a/scripts/plot/text.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/text.m	Tue Dec 06 13:09:17 2011 -0800
@@ -17,13 +17,17 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{label})
-## @deftypefnx {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{z}, @var{label})
-## @deftypefnx {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{label}, @var{p1}, @var{v1}, @dots{})
-## @deftypefnx {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{z}, @var{label}, @var{p1}, @var{v1}, @dots{})
+## @deftypefn  {Function File} {} text (@var{x}, @var{y}, @var{label})
+## @deftypefnx {Function File} {} text (@var{x}, @var{y}, @var{z}, @var{label})
+## @deftypefnx {Function File} {} text (@var{x}, @var{y}, @var{label}, @var{p1}, @var{v1}, @dots{})
+## @deftypefnx {Function File} {} text (@var{x}, @var{y}, @var{z}, @var{label}, @var{p1}, @var{v1}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} text (@dots{})
 ## Create a text object with text @var{label} at position @var{x},
 ## @var{y}, @var{z} on the current axes.  Property-value pairs following
 ## @var{label} may be used to specify the appearance of the text.
+##
+## The optional return value @var{h} is a graphics handle to the created text
+## object.
 ## @end deftypefn
 
 ## Author: jwe
@@ -134,17 +138,17 @@
 %!       text (x(nh), y(nv), "Hello World", ...
 %!             "rotation", t, ...
 %!             "horizontalalignment", ha{nh}, ...
-%!             "verticalalignment", va{nv})
+%!             "verticalalignment", va{nv});
 %!     endfor
 %!   endfor
 %! endfor
 %! set (gca, "xtick", [0.25, 0.5, 0.75], ...
 %!           "xticklabel", ha, ...
 %!           "ytick", [0.25, 0.5, 0.75], ...
-%!           "yticklabel", va)
-%! axis ([0 1 0 1])
-%! xlabel ("horizontal alignment")
-%! ylabel ("vertical alignment")
+%!           "yticklabel", va);
+%! axis ([0 1 0 1]);
+%! xlabel ("horizontal alignment");
+%! ylabel ("vertical alignment");
 %! title ("text alignment and rotation (0:30:360 degrees)")
 
 %!demo
@@ -156,20 +160,20 @@
 %!   text (25, 25, 0, "Vertical Alignment = Bottom", ...
 %!                    "rotation", t, ...
 %!                    "horizontalalignment", "left", ...
-%!                    "verticalalignment", "bottom")
+%!                    "verticalalignment", "bottom");
 %! endfor
-%! caxis ([-100 100])
-%! title ("Vertically Aligned at Bottom")
+%! caxis ([-100 100]);
+%! title ("Vertically Aligned at Bottom");
 
 %!demo
 %! clf
-%! axis ([0 8 0 8])
-%! title (["1st title";"2nd title"])
-%! xlabel (["1st xlabel";"2nd xlabel"])
-%! ylabel (["1st ylabel";"2nd ylabel"])
+%! axis ([0 8 0 8]);
+%! title (["1st title";"2nd title"]);
+%! xlabel (["1st xlabel";"2nd xlabel"]);
+%! ylabel (["1st ylabel";"2nd ylabel"]);
 %! text (4, 4, {"Hello", "World"}, ...
 %!       "horizontalalignment", "center", ...
-%!       "verticalalignment", "middle")
+%!       "verticalalignment", "middle");
 %! grid on
 
 %!demo
@@ -177,74 +181,74 @@
 %! h = mesh (peaks, "edgecolor", 0.7 * [1 1 1], ...
 %!                  "facecolor", "none", ...
 %!                  "facealpha", 0);
-%! title (["1st title";"2nd title"])
-%! xlabel (["1st xlabel";"2nd xlabel"])
-%! ylabel (["1st ylabel";"2nd ylabel"])
-%! zlabel (["1st zlabel";"2nd zlabel"])
+%! title (["1st title";"2nd title"]);
+%! xlabel (["1st xlabel";"2nd xlabel"]);
+%! ylabel (["1st ylabel";"2nd ylabel"]);
+%! zlabel (["1st zlabel";"2nd zlabel"]);
 %! text (0, 0, 5, {"Hello", "World"}, ...
 %!       "horizontalalignment", "center", ...
-%!       "verticalalignment", "middle")
-%! hold on
-%! plot3 (0, 0, 5, "+k")
-%!
+%!       "verticalalignment", "middle");
+%! hold on;
+%! plot3 (0, 0, 5, "+k");
 
 %!demo
 %! clf
 %! h = text (0.5, 0.3, "char");
-%! assert ("char", class (get (h, "string")))
+%! assert ("char", class (get (h, "string")));
 %! h = text (0.5, 0.4, ["char row 1"; "char row 2"]);
-%! assert ("char", class (get (h, "string")))
+%! assert ("char", class (get (h, "string")));
 %! h = text (0.5, 0.6, {"cell2str (1,1)", "cell2str (1,2)"; "cell2str (2,1)", "cell2str (2,2)"});
-%! assert ("cell", class (get (h, "string")))
+%! assert ("cell", class (get (h, "string")));
 %! h = text (0.5, 0.8, "foobar");
-%! set (h, "string", 1:3)
+%! set (h, "string", 1:3);
 %! h = text ([0.1, 0.1], [0.3, 0.4], "one string & two objects");
-%! assert ("char", class (get (h(1), "string")))
-%! assert ("char", class (get (h(2), "string")))
+%! assert ("char", class (get (h(1), "string")));
+%! assert ("char", class (get (h(2), "string")));
 %! h = text ([0.1, 0.1], [0.5, 0.6], {"one cellstr & two objects"});
-%! assert ("cell", class (get (h(1), "string")))
-%! assert ("cell", class (get (h(2), "string")))
+%! assert ("cell", class (get (h(1), "string")));
+%! assert ("cell", class (get (h(2), "string")));
 %! h = text ([0.1, 0.1], [0.7, 0.8], {"cellstr 1 object 1", "cellstr 2 object 2"});
-%! assert ("char", class (get (h(1), "string")))
-%! assert ("char", class (get (h(2), "string")))
+%! assert ("char", class (get (h(1), "string")));
+%! assert ("char", class (get (h(2), "string")));
 %! h = text ([0.1, 0.1], [0.1, 0.2], ["1st string & 1st object"; "2nd string & 2nd object"]);
-%! assert ("char", class (get (h(1), "string")))
-%! assert ("char", class (get (h(2), "string")))
+%! assert ("char", class (get (h(1), "string")));
+%! assert ("char", class (get (h(2), "string")));
 %! h = text (0.7, 0.6, "single string");
-%! assert ("char", class (get (h, "string")))
+%! assert ("char", class (get (h, "string")));
 %! h = text (0.7, 0.5, {"single cell-string"});
-%! assert ("cell", class (get (h, "string")))
-%! xlabel (1:2)
-%! ylabel (1:2)
-%! title (1:2)
+%! assert ("cell", class (get (h, "string")));
+%! xlabel (1:2);
+%! ylabel (1:2);
+%! title (1:2);
 
 %!test
 %! hf = figure ("visible", "off");
 %! unwind_protect
 %!   h = text (0.5, 0.3, "char");
-%!   assert ("char", class (get (h, "string")))
+%!   assert ("char", class (get (h, "string")));
 %!   h = text (0.5, 0.4, ["char row 1"; "char row 2"]);
-%!   assert ("char", class (get (h, "string")))
+%!   assert ("char", class (get (h, "string")));
 %!   h = text (0.5, 0.6, {"cell2str (1,1)", "cell2str (1,2)"; "cell2str (2,1)", "cell2str (2,2)"});
-%!   assert ("cell", class (get (h, "string")))
+%!   assert ("cell", class (get (h, "string")));
 %!   h = text (0.5, 0.8, "foobar");
-%!   set (h, "string", 1:3)
+%!   set (h, "string", 1:3);
 %!   h = text ([0.1, 0.1], [0.3, 0.4], "one string & two objects");
-%!   assert ("char", class (get (h(1), "string")))
-%!   assert ("char", class (get (h(2), "string")))
+%!   assert ("char", class (get (h(1), "string")));
+%!   assert ("char", class (get (h(2), "string")));
 %!   h = text ([0.1, 0.1], [0.5, 0.6], {"one cellstr & two objects"});
-%!   assert ("cell", class (get (h(1), "string")))
-%!   assert ("cell", class (get (h(2), "string")))
+%!   assert ("cell", class (get (h(1), "string")));
+%!   assert ("cell", class (get (h(2), "string")));
 %!   h = text ([0.1, 0.1], [0.7, 0.8], {"cellstr 1 object 1", "cellstr 2 object 2"});
-%!   assert ("char", class (get (h(1), "string")))
-%!   assert ("char", class (get (h(2), "string")))
+%!   assert ("char", class (get (h(1), "string")));
+%!   assert ("char", class (get (h(2), "string")));
 %!   h = text ([0.1, 0.1], [0.1, 0.2], ["1st string & 1st object"; "2nd string & 2nd object"]);
-%!   assert ("char", class (get (h(1), "string")))
-%!   assert ("char", class (get (h(2), "string")))
+%!   assert ("char", class (get (h(1), "string")));
+%!   assert ("char", class (get (h(2), "string")));
 %!   h = text (0.7, 0.6, "single string");
-%!   assert ("char", class (get (h, "string")))
+%!   assert ("char", class (get (h, "string")));
 %!   h = text (0.7, 0.5, {"single cell-string"});
-%!   assert ("cell", class (get (h, "string")))
+%!   assert ("cell", class (get (h, "string")));
 %! unwind_protect_cleanup
 %!   close (hf);
 %! end_unwind_protect
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/title.m
--- a/scripts/plot/title.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/title.m	Tue Dec 06 13:09:17 2011 -0800
@@ -21,7 +21,9 @@
 ## @deftypefnx {Function File} {} title (@var{string}, @var{p1}, @var{v1}, @dots{})
 ## @deftypefnx {Function File} {} title (@var{h}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} title (@dots{})
-## Create a title object and return a handle to it.
+## Create a title object for a plot.
+##
+## The optional return value @var{h} is a graphics handle to the created object.
 ## @end deftypefn
 
 ## Author: jwe
@@ -42,27 +44,28 @@
 
 endfunction
 
+
 %!demo
 %! clf ();
-%! ax=axes();
-%! xl = get(ax,"title");
-%! title("Testing title")
-%! assert(get(xl,"string"),"Testing title")
+%! ax = axes();
+%! xl = get (ax,"title");
+%! title ("Testing title");
+%! assert (get (xl,"string"), "Testing title");
 
 %!demo
 %! clf ();
 %! plot3 ([0,1], [0,1], [0,1]);
 %! xl = get(gca (), "title");
-%! title("Testing title")
-%! assert(get(xl,"string"),"Testing title")
+%! title ("Testing title");
+%! assert (get (xl,"string"),"Testing title");
 
 %!test
 %! hf = figure ("visible", "off");
 %! unwind_protect
-%!   ax=axes();
-%!   xl = get(ax,"title");
-%!   title("Testing title")
-%!   assert(get(xl,"string"),"Testing title")
+%!   ax = axes();
+%!   xl = get (ax,"title");
+%!   title ("Testing title");
+%!   assert (get (xl,"string"), "Testing title");
 %! unwind_protect_cleanup
 %!   close (hf);
 %! end_unwind_protect
@@ -71,9 +74,10 @@
 %! hf = figure ("visible", "off");
 %! unwind_protect
 %!   plot3 ([0,1], [0,1], [0,1]);
-%!   xl = get(gca (), "title");
-%!   title("Testing title")
-%!   assert(get(xl,"string"),"Testing title")
+%!   xl = get (gca (), "title");
+%!   title("Testing title");
+%!   assert (get (xl,"string"), "Testing title");
 %! unwind_protect_cleanup
 %!   close (hf);
 %! end_unwind_protect
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/trimesh.m
--- a/scripts/plot/trimesh.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/trimesh.m	Tue Dec 06 13:09:17 2011 -0800
@@ -22,8 +22,9 @@
 ## Plot a triangular mesh in 3D@.  The variable @var{tri} is the triangular
 ## meshing of the points @code{(@var{x}, @var{y})} which is returned
 ## from @code{delaunay}.  The variable @var{z} is value at the point
-## @code{(@var{x}, @var{y})}.  The output argument @var{h} is the graphic
-## handle of the plot.
+## @code{(@var{x}, @var{y})}.
+##
+## The optional return value @var{h} is a graphics handle to the created plot.
 ## @seealso{triplot, trisurf, delaunay3}
 ## @end deftypefn
 
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/triplot.m
--- a/scripts/plot/triplot.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/triplot.m	Tue Dec 06 13:09:17 2011 -0800
@@ -23,8 +23,9 @@
 ## Plot a triangular mesh in 2D@.  The variable @var{tri} is the triangular
 ## meshing of the points @code{(@var{x}, @var{y})} which is returned from
 ## @code{delaunay}.  If given, @var{linespec} determines the properties
-## to use for the lines.  The output argument @var{h} is the graphic handle
-## of the plot.
+## to use for the lines. 
+##
+## The optional return value @var{h} is a graphics handle to the created plot.
 ## @seealso{plot, trimesh, trisurf, delaunay}
 ## @end deftypefn
 
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/trisurf.m
--- a/scripts/plot/trisurf.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/trisurf.m	Tue Dec 06 13:09:17 2011 -0800
@@ -22,8 +22,9 @@
 ## Plot a triangular surface in 3D@.  The variable @var{tri} is the triangular
 ## meshing of the points @code{(@var{x}, @var{y})} which is returned
 ## from @code{delaunay}.  The variable @var{z} is value at the point
-## @code{(@var{x}, @var{y})}.  The output argument @var{h} is the graphic
-## handle of the plot.
+## @code{(@var{x}, @var{y})}.
+##
+## The optional return value @var{h} is a graphics handle to the created plot.
 ## @seealso{triplot, trimesh, delaunay3}
 ## @end deftypefn
 
@@ -87,19 +88,19 @@
 %! y = rand (100, 1);
 %! z = x.^2 + y.^2;
 %! tri = delaunay (x, y);
-%! trisurf (tri, x, y, z)
+%! trisurf (tri, x, y, z);
 
 %!demo
 %! x = rand (100, 1);
 %! y = rand (100, 1);
 %! z = x.^2 + y.^2;
 %! tri = delaunay (x, y);
-%! trisurf (tri, x, y, z, "facecolor", "interp")
+%! trisurf (tri, x, y, z, "facecolor", "interp");
 
 %!demo
 %! x = rand (100, 1);
 %! y = rand (100, 1);
 %! z = x.^2 + y.^2;
 %! tri = delaunay (x, y);
-%! trisurf (tri, x, y, z, "facecolor", "interp", "edgecolor", "k")
+%! trisurf (tri, x, y, z, "facecolor", "interp", "edgecolor", "k");
 
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/xlabel.m
--- a/scripts/plot/xlabel.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/xlabel.m	Tue Dec 06 13:09:17 2011 -0800
@@ -23,10 +23,10 @@
 ## @deftypefnx {Function File} {} ylabel (@dots{})
 ## @deftypefnx {Function File} {} zlabel (@dots{})
 ## Specify x-, y-, or z-axis labels for the current axis.  If @var{h} is
-## specified then label the axis defined by @var{h}.  The optional return
-## value @var{h} provides a handle to the created label.
-## @seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
-## bar, stairs, title}
+## specified then label the axis defined by @var{h}.
+##
+## The optional return value @var{h} is a graphics handle to the created object.
+## @seealso{title, text}
 ## @end deftypefn
 
 ## Author: jwe
@@ -48,14 +48,16 @@
 
 endfunction
 
+
 %!test
 %! hf = figure ("visible", "off");
 %! unwind_protect
 %!   x = xlabel ("xlabel_string");
-%!   assert (get(gca, "xlabel"), x);
-%!   assert (get(x, "type"), "text");
-%!   assert (get(x, "visible"), "on");
-%!   assert (get(x, "string"), "xlabel_string");
+%!   assert (get (gca, "xlabel"), x);
+%!   assert (get (x, "type"), "text");
+%!   assert (get (x, "visible"), "on");
+%!   assert (get (x, "string"), "xlabel_string");
 %! unwind_protect_cleanup
 %!   close (hf);
 %! end_unwind_protect
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/ylabel.m
--- a/scripts/plot/ylabel.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/ylabel.m	Tue Dec 06 13:09:17 2011 -0800
@@ -42,14 +42,16 @@
 
 endfunction
 
+
 %!test
 %! hf = figure ("visible", "off");
 %! unwind_protect
 %!   y = ylabel ("ylabel_string");
-%!   assert (get(gca, "ylabel"), y);
-%!   assert (get(y, "type"), "text");
-%!   assert (get(y, "visible"), "on");
-%!   assert (get(y, "string"), "ylabel_string");
+%!   assert (get (gca, "ylabel"), y);
+%!   assert (get (y, "type"), "text");
+%!   assert (get (y, "visible"), "on");
+%!   assert (get (y, "string"), "ylabel_string");
 %! unwind_protect_cleanup
 %!   close (hf);
 %! end_unwind_protect
+
diff -r 15400d5deb1c -r 5f0bb45e615c scripts/plot/zlabel.m
--- a/scripts/plot/zlabel.m	Mon Dec 05 17:13:35 2011 -0800
+++ b/scripts/plot/zlabel.m	Tue Dec 06 13:09:17 2011 -0800
@@ -42,14 +42,15 @@
 
 endfunction
 
+
 %!test
 %! hf = figure ("visible", "off");
 %! unwind_protect
 %!   z = zlabel ("zlabel_string");
-%!   assert (get(gca, "zlabel"), z);
-%!   assert (get(z, "type"), "text");
-%!   assert (get(z, "visible"), "off");
-%!   assert (get(z, "string"), "zlabel_string");
+%!   assert (get (gca, "zlabel"), z);
+%!   assert (get (z, "type"), "text");
+%!   assert (get (z, "visible"), "off");
+%!   assert (get (z, "string"), "zlabel_string");
 %! unwind_protect_cleanup
 %!   close (hf);
 %! end_unwind_protect
@@ -59,10 +60,11 @@
 %! plot3 (0, 0, 0);
 %! unwind_protect
 %!   z = zlabel ("zlabel_string");
-%!   assert (get(gca, "zlabel"), z);
-%!   assert (get(z, "type"), "text");
-%!   assert (get(z, "visible"), "off");
-%!   assert (get(z, "string"), "zlabel_string");
+%!   assert (get (gca, "zlabel"), z);
+%!   assert (get (z, "type"), "text");
+%!   assert (get (z, "visible"), "off");
+%!   assert (get (z, "string"), "zlabel_string");
 %! unwind_protect_cleanup
 %!   close (hf);
 %! end_unwind_protect
+