--- a/scripts/plot/isonormals.m
+++ b/scripts/plot/isonormals.m
@@ -12,17 +12,83 @@
 ##
 ## You should have received a copy of the GNU General Public License
 ## along with this program; if not, see http://www.gnu.org/licenses/gpl.html.
-##
-## Author: Martin Helm <martin@mhelm.de>
 
-## usage: NORMALS = isonormals(X,Y,Z,V,VERT)
-## usage: NORMALS = isonormals(V,VERT)
-## usage: NORMALS = isonormals(V,P)
-## usage: NORMALS = isonormals(X,Y,Z,V,P)
-## usage: NORMALS = isonormals(...,'negate')
-## usage: isonormals(V,P)
-## usage: isonormals(X,Y,Z,V,P)
+## -*- texinfo -*-
+## @deftypefn  {Function File} {[@var{n}] =} isonormals (@var{val}, @var{v})
+## @deftypefnx {Function File} {[@var{n}] =} isonormals (@var{val}, @var{p})
+## @deftypefnx {Function File} {[@var{n}] =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{v})
+## @deftypefnx {Function File} {[@var{n}] =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{p})
+## @deftypefnx {Function File} {[@var{n}] =} isonormals (@dots{}, "negate")
+## @deftypefnx {Function File} isonormals (@dots{}, @var{p})
+##
+## If called with one output argument and the first input argument
+## @var{val} is a three--dimensional array that contains the data for an
+## isosurface geometry and the second input argument @var{v} keeps the
+## vertices of an isosurface then return the normals @var{n} in form of
+## a matrix with the same size than @var{v} at computed points
+## @command{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}.  The output argument
+## @var{n} can be taken to manually set @var{VertexNormals} of a patch.
+##
+## If called with further input arguments @var{x}, @var{y} and @var{z}
+## which are three--dimensional arrays with the same size than @var{val}
+## then the volume data is taken at those given points.  Instead of the
+## vertices data @var{v} a patch handle @var{p} can be passed to this
+## function.
+##
+## If given the string input argument "negate" as last input argument
+## then compute the reverse vector normals of an isosurface geometry.
+##
+## If no output argument is given then directly redraw the patch that is
+## given by the patch handle @var{p}.
+##
+## For example,
+## @example
+## function [] = isofinish (p)
+##   set (gca, "DataAspectRatioMode","manual","DataAspectRatio",[1 1 1]);
+##   set (p, "VertexNormals", -get(p,"VertexNormals")); ## Revert normals
+##   set (p, "FaceColor", "interp");
+##   ## set (p, "FaceLighting", "phong");
+##   ## light ("Position", [1 1 5]); ## Available with JHandles
+## endfunction
 ##
+## N = 15;    ## Increase number of vertices in each direction
+## iso = .4;  ## Change isovalue to .1 to display a sphere
+## lin = linspace (0, 2, N);
+## [x, y, z] = meshgrid (lin, lin, lin);
+## c = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2);
+## figure (); ## Open another figure window
+##
+## subplot (2, 2, 1); view (-38, 20);
+## [f, v, cdat] = isosurface (x, y, z, c, iso, y);
+## p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, \
+## 	   "FaceColor", "interp", "EdgeColor", "none");
+## isofinish (p); ## Call user function isofinish
+##
+## subplot (2, 2, 2); view (-38, 20);
+## p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, \
+## 	   "FaceColor", "interp", "EdgeColor", "none");
+## isonormals (x, y, z, c, p); ## Directly modify patch
+## isofinish (p);
+##
+## subplot (2, 2, 3); view (-38, 20);
+## p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, \
+## 	   "FaceColor", "interp", "EdgeColor", "none");
+## n = isonormals (x, y, z, c, v); ## Compute normals of isosurface
+## set (p, "VertexNormals", n);    ## Manually set vertex normals
+## isofinish (p);
+##
+## subplot (2, 2, 4); view (-38, 20);
+## p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, \
+## 	   "FaceColor", "interp", "EdgeColor", "none");
+## isonormals (x, y, z, c, v, "negate"); ## Use reverse directly
+## isofinish (p);
+## @end example
+##
+## @seealso {isosurface, isocolors, isocaps, marching_cube}
+##
+## @end deftypefn
+
+## Author: Martin Helm <martin@mhelm.de>
 
 function varargout = isonormals(varargin)
   na = nargin;
@@ -75,4 +141,18 @@
     otherwise
       print_usage ();
   endswitch
-endfunction
\ No newline at end of file
+endfunction
+
+%!test
+%!  [x, y, z] = meshgrid (0:.5:2, 0:.5:2, 0:.5:2);
+%!  c = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2); 
+%!  [f, v, cdat] = isosurface (x, y, z, c, .4, y);
+%!  n = isonormals (x, y, z, c, v);
+%!  assert (size (v), size (n));
+%!test
+%!  [x, y, z] = meshgrid (0:.5:2, 0:.5:2, 0:.5:2);
+%!  c = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2); 
+%!  [f, v, cdat] = isosurface (x, y, z, c, .4, y);
+%!  np = isonormals (x, y, z, c, v);
+%!  nn = isonormals (x, y, z, c, v, "negate");
+%!  assert (all (np == -nn));