# HG changeset patch
# User Rik <rik@octave.org>
# Date 1355348927 28800
# Node ID 0f1a143e50020d4c8c2d804f992553785a8e3cf2
# Parent  4698ea77aa756ae2ee7b46c14c0a093cd30cb8a1
Overhaul scripts/java directory to conform to Octave core.
Update docstrings.  Use Octave coding conventions.  Use default arguments
where possible.  Match variable names in docstring to variable names in
function.

HG: Enter commit message.  Lines beginning with 'HG:' are removed.
HG: Leave message empty to abort commit.
HG: --
HG: user: Rik <rik@octave.org>
HG: branch 'default'
* errordlg.m, helpdlg.m, inputdlg.m, javaArray.m, javaaddpath.m,
javaclasspath.m, javafields.m, javamem.m, javamethods.m, javarmpath.m,
listdlg.m, msgbox.m, questdlg.m, warndlg.m: Overhaul functions.
Update docstrings.  Use Octave coding conventions.  Use default arguments
where possible.  Match variable names in docstring to variable names in
function.

diff --git a/scripts/java/errordlg.m b/scripts/java/errordlg.m
--- a/scripts/java/errordlg.m
+++ b/scripts/java/errordlg.m
@@ -17,40 +17,38 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function file} {@var{p} =} errordlg (@var{msg}, @var{title})
+## @deftypefn  {Function File} {@var{h} =} errordlg (@var{msg})
+## @deftypefnx {Function File} {@var{h} =} errordlg (@var{msg}, @var{title})
 ## Display @var{msg} using an error dialog box.
 ##
 ## The message may have multiple lines separated by newline characters
-## (@code{"\n"}), or it may be a cellstr array with one element for each
-## line.  The optional @var{title} (character string) can be used to
-## decorate the dialog caption.
+## ("\n"), or it may be a cellstr array with one element for each
+## line.  The optional input @var{title} (character string) can be used to
+## set the dialog caption.  The default title is "Error Dialog".
 ##
 ## The return value is always 1.
-## @seealso{helpdlg, inputdlg, listdlg, questdlg, warndlg}
+## @seealso{helpdlg, inputdlg, listdlg, msgbox, questdlg, warndlg}
 ## @end deftypefn
 
-function retval = errordlg (message, varargin)
+function h = errordlg (msg, title = "Error Dialog")
+
+  if (nargin < 1 || nargin > 2)
+    print_usage ();
+  endif
 
-  if (! ischar (message))
-    if (iscell (message))
-      message = cell2mlstr (message);
+  if (! ischar (msg))
+    if (iscell (msg))
+      msg = cell2mlstr (msg);
     else
-      error ("errordlg: character string or cellstr array expected for message");
+      error ("errordlg: MSG must be a string or cellstr array");
     endif
   endif
 
-  switch (numel (varargin))
-    case 0
-      title = "Error Dialog";
-
-    otherwise
-      title = varargin{1};
-  endswitch
-
   if (! ischar (title))
-    error ("errordlg: character string expected for title");
+    error ("errordlg: TITLE must be a character string");
   endif
 
-  retval = java_invoke ("org.octave.JDialogBox", "errordlg", message, title);
+  h = java_invoke ("org.octave.JDialogBox", "errordlg", msg, title);
 
 endfunction
+
diff --git a/scripts/java/helpdlg.m b/scripts/java/helpdlg.m
--- a/scripts/java/helpdlg.m
+++ b/scripts/java/helpdlg.m
@@ -17,44 +17,38 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function file} {@var{p} =} helpdlg (@var{msg} ,@var{title}])
+## @deftypefn  {Function File} {@var{h} =} helpdlg (@var{msg})
+## @deftypefnx {Function File} {@var{h} =} helpdlg (@var{msg}, @var{title})
 ## Display @var{msg} in a help dialog box.
 ##
 ## The message may have multiple lines separated by newline characters
-## (@code{"\n"}), or it may be a cellstr array with one element for each
-## line.  The optional @var{title} (character string) can be used to
-## decorate the dialog caption.
+## ("\n"), or it may be a cellstr array with one element for each
+## line.  The optional input @var{title} (character string) can be used to
+## set the dialog caption.  The default title is "Help Dialog".
 ##
 ## The return value is always 1.
-## @seealso{errordlg, inputdlg, listdlg, questdlg, warndlg}
+## @seealso{errordlg, inputdlg, listdlg, msgbox, questdlg, warndlg}
 ## @end deftypefn
 
-function retval = helpdlg (message, varargin)
+function h = helpdlg (msg, title = "Help Dialog")
+
+  if (nargin < 1 || nargin > 2)
+    print_usage ();
+  endif
 
-  if (! ischar (message))
-    if (iscell (message))
-      message = cell2mlstr (message);
+  if (! ischar (msg))
+    if (iscell (msg))
+      msg = cell2mlstr (msg);
     else
-      error ("helpdlg: character string or cellstr array expected for message");
+      error ("helpdlg: MSG must be a string or cellstr array");
     endif
   endif
-  
-  switch (numel (varargin))
-    case 0
-      title = "Help Dialog";
-
-    otherwise
-      if (ischar (varargin {1}))
-        title = varargin{1};
-      else
-        error ("helpdlg: character string expected for title");
-      endif
-  endswitch
 
   if (! ischar (title))
-    error ("helpdlg: character string expected for title");
+    error ("helpdlg: TITLE must be a character string");
   endif
 
-  retval = java_invoke ("org.octave.JDialogBox", "helpdlg", message, title);
+  h = java_invoke ("org.octave.JDialogBox", "helpdlg", msg, title);
 
 endfunction
+
diff --git a/scripts/java/inputdlg.m b/scripts/java/inputdlg.m
--- a/scripts/java/inputdlg.m
+++ b/scripts/java/inputdlg.m
@@ -17,99 +17,109 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function file} {@var{p} =} inputdlg (@var{prompt}, @var{title}, @var{rowscols}, @var{defaults})
+## @deftypefn  {Function File} {@var{cstr} =} inputdlg (@var{prompt})
+## @deftypefnx {Function File} {@var{cstr} =} inputdlg (@var{prompt}, @var{title})
+## @deftypefnx {Function File} {@var{cstr} =} inputdlg (@var{prompt}, @var{title}, @var{rowscols})
+## @deftypefnx {Function File} {@var{cstr} =} inputdlg (@var{prompt}, @var{title}, @var{rowscols}, @var{defaults})
 ## Return user input from a multi-textfield dialog box in a cell array
 ## of strings, or an empty cell array if the dialog is closed by the
 ## Cancel button.
 ##
+## Inputs:
+##
 ## @table @var
 ## @item prompt
-## The first argument @var{prompt} is mandatory.
-## It is a cell array with strings labeling each textfield. 
+## A cell array with strings labeling each text field.  This input is required. 
+##
 ## @item title
-## The optional string @var{title} can be used as the caption of the dialog. 
+## String to use for the caption of the dialog.  The default is "Input Dialog".
+##
 ## @item rowscols
-## The size of the text fields can be defined by the argument @var{rowscols}, 
-## which can have three forms:
+## Specifies the size of the text fields and can take three forms:
+##
 ## @enumerate
 ## @item a scalar value which defines the number of rows used for each
 ## text field.
+##
 ## @item a vector which defines the individual number of rows
 ## used for each text field. 
+##
 ## @item a matrix which defines the individual number of rows and
-## columns used for each text field.
+## columns used for each text field.  In the matrix each row describes
+## a single text field.  The first column specifies the number of input
+## rows to use and the second column specifies the text field width.
 ## @end enumerate
+##
 ## @item defaults
-## It is possible to place default values into the text fields by supplying
-## the a cell array of strings or number for the argument @var{defaults}.
+## A list of default values to place in each text fields.  It must be
+## a cell array of strings with the same size as @var{prompt}.
 ## @end table
-## @seealso{errordlg, helpdlg, listdlg, questdlg, warndlg}
+## @seealso{errordlg, helpdlg, listdlg, msgbox, questdlg, warndlg}
 ## @end deftypefn
 
-function retval = inputdlg (prompt, varargin)
+function cstr = inputdlg (prompt, title = "Input Dialog", varargin)
+
+  if (nargin < 1 || nargin > 4)
+    print_usage ();
+  endif
 
   if (iscell (prompt))
     ## Silently extract only char elements
-    prompt = prompt (find (cellfun ("ischar", prompt)));
+    prompt = prompt(cellfun ("ischar", prompt));
   elseif (ischar (prompt))
     prompt = {prompt};
   else
-    error ("inputdlg: character string or cellstr array expected for prompt");
+    error ("inputdlg: PROMPT must be a character string or cellstr array");
+  endif
+
+  if (! ischar (title))
+    error ("inputdlg: TITLE must be a character string");
   endif
 
   switch (numel (varargin))
     case 0
-      title = "Input Dialog";
-      lineNo = 1;
-      defaults = cellstr (cell( size (prompt)));
+      linespec = 1;
+      defaults = cellstr (cell (size (prompt)));
 
     case 1
-      title = varargin{1};
-      lineNo = 1;
+      linespec = varargin{1};
       defaults = cellstr (cell (size (prompt)));
 
     case 2
-      title = varargin{1};
-      lineNo = varargin{2};
-      defaults = cellstr (cell (size (prompt)));
-
-    otherwise
-      title = varargin{1};
-      lineNo = varargin{2};
-      defaults = varargin{3};
+      linespec = varargin{1};
+      defaults = varargin{2};
   endswitch
 
-  if (! ischar (title))
-    error ("inputdlg: character string expected for title");
-  endif
-
   ## specification of text field sizes as in Matlab 
-  ## Matlab requires a matrix for lineNo, not a cell array...
+  ## Matlab requires a matrix for linespec, not a cell array...
   ## rc = [1,10; 2,20; 3,30];
   ##     c1  c2
   ## r1  1   10   first  text field is 1x10
   ## r2  2   20   second text field is 2x20
   ## r3  3   30   third  text field is 3x30
-  if (isscalar (lineNo))
-    ## only scalar value in lineTo, copy from lineNo and add defaults
-    rowscols = zeros(size(prompt)(2),2);
+  if (isscalar (linespec))
+    ## only scalar value in lineTo, copy from linespec and add defaults
+    rowscols = zeros (columns (prompt), 2);
     ## cols
     rowscols(:,2) = 25;
-    rowscols(:,1) = lineNo;
-  elseif (isvector (lineNo))
-      ## only one column in lineTo, copy from vector lineNo and add defaults
+    rowscols(:,1) = linespec;
+  elseif (isvector (linespec))
+      ## only one column in lineTo, copy from vector linespec and add defaults
       rowscols = zeros (columns (prompt), 2);
-      ## rows from colum vector lineNo, columns are set to default
+      ## rows from colum vector linespec, columns are set to default
       rowscols(:,2) = 25;
-      rowscols(:,1) = lineNo(:);         
-  elseif (ismatrix (lineNo))
-    if (rows (lineNo) == columns (prompt) && columns (lineNo) == 2)
-      ## (rows x columns) match, copy array lineNo
-      rowscols = lineNo;
+      rowscols(:,1) = linespec(:);
+  elseif (ismatrix (linespec))
+    if (rows (linespec) == columns (prompt) && columns (linespec) == 2)
+      ## (rows x columns) match, copy array linespec
+      rowscols = linespec;
+    else
+      error ("inputdlg: ROWSCOLS matrix does not match size of PROMPT");
     endif
+
   else
     ## dunno
-    error ("inputdlg: unknown form of lineNo argument");
+    error ("inputdlg: unknown form of ROWSCOLS argument");
   endif
   
   ## convert numeric values in defaults cell array to strings
@@ -120,9 +130,9 @@
                              prompt, title, rc, defs);
   
    if (isempty (user_inputs))
-     retval = {};
+     cstr = {};
    else
-     retval = cellstr (user_inputs);
+     cstr = cellstr (user_inputs);
    endif
 
 endfunction
diff --git a/scripts/java/javaArray.m b/scripts/java/javaArray.m
--- a/scripts/java/javaArray.m
+++ b/scripts/java/javaArray.m
@@ -17,39 +17,35 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function file} {@var{a} =} javaArray (@var{class}, @var{sz})
-## @deftypefnx {Function file} {@var{a} =} javaArray (@var{class}, @var{m}, @var{n}, @dots{})
+## @deftypefn  {Function File} {@var{a} =} javaArray (@var{classname}, @var{sz})
+## @deftypefnx {Function File} {@var{a} =} javaArray (@var{classname}, @var{m}, @var{n}, @dots{})
 ##
-## Creates a Java array of size @var{sz} with elements of class
-## @var{class}.  @var{class} may be a Java object representing a class
+## Create a Java array of size @var{sz} with elements of class
+## @var{classname}.  @var{classname} may be a Java object representing a class
 ## or a string containing the fully qualified class name.  The size of
 ## the object may also be specified with individual integer arguments
 ## @var{m}, @var{n}, etc.
 ##
-## The generated array is uninitialized, all elements are set to null
-## if @var{class} is a reference type, or to a default value (usually 0)
-## if @var{class} is a primitive type.
+## The generated array is uninitialized.  All elements are set to null
+## if @var{classname} is a reference type, or to a default value (usually 0)
+## if @var{classname} is a primitive type.
 ##
 ## @example
+## @group
 ## a = javaArray ("java.lang.String", 2, 2);
 ## a(1,1) = "Hello";
+## @end group
 ## @end example
 ## @end deftypefn
 
-function retval = javaArray (class_name, varargin)
-
-  switch (numel (varargin))
-    case 0
-      error ("missing array size");
+function retval = javaArray (classname, varargin)
 
-    case 1
-      dims = varargin{1};
-
-    otherwise
-      dims = [varargin{:}];
-  endswitch
+  if (nargin < 2)
+    print_usage ();
+  endif
 
   retval = java_invoke ("org.octave.ClassHelper", "createArray",
-                        class_name, dims);
+                        classname, [varargin{:}]);
 
 endfunction
+
diff --git a/scripts/java/javaaddpath.m b/scripts/java/javaaddpath.m
--- a/scripts/java/javaaddpath.m
+++ b/scripts/java/javaaddpath.m
@@ -18,31 +18,42 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function file} {} javaaddpath (@var{path})
-## Add @var{path} to the dynamic class path of the Java virtual
-## machine.  @var{path} may be either a directory where @file{.class}
+## @deftypefn  {Function File} {} javaaddpath (@var{clspath})
+## @deftypefnx {Function File} {} javaaddpath (@var{clspath1}, @dots{})
+## Add @var{clspath} to the dynamic class path of the Java virtual
+## machine.  @var{clspath} may either be a directory where @file{.class}
 ## files are found, or a @file{.jar} file containing Java classes.
-## @seealso{javaclasspath}
+## Multiple paths may be added at once by specifying additional arguments.
+## @seealso{javarmpath, javaclasspath}
 ## @end deftypefn
 
-function javaaddpath (class_path)
+function javaaddpath (varargin)
 
-  if (nargin != 1)
+  if (nargin < 1)
     print_usage ();
-  else
-    new_path = canonicalize_file_name (tilde_expand (class_path));
+  endif
+
+  for i = 1:numel (varargin)
+    clspath = varargin{i};
+    if (! ischar (clspath))
+      error ("javaaddpath: CLSPATH must be a string");
+    endif
+
+    new_path = canonicalize_file_name (tilde_expand (clspath));
     if (exist (new_path, "dir"))
-      if (! strcmp (new_path (end), filesep))
-        new_path = [new_path, filesep];
+      if (new_path(end) != filesep ())
+        new_path = [new_path, filesep()];
       endif
     elseif (! exist (new_path, "file"))
-      error ("invalid Java classpath: %s", class_path);
+      error ("javaaddpath: CLSPATH does not exist: %s", clspath);
     endif
+
     success = java_invoke ("org.octave.ClassHelper", "addClassPath", new_path);
 
     if (! success)
       warning ("javaaddpath: failed to add '%s' to Java classpath", new_path);
     endif
-  endif 
+  endfor 
    
 endfunction
+
diff --git a/scripts/java/javaclasspath.m b/scripts/java/javaclasspath.m
--- a/scripts/java/javaclasspath.m
+++ b/scripts/java/javaclasspath.m
@@ -18,31 +18,39 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function file}  {} javaclasspath ()
-## @deftypefnx {Function file} {@var{static} =} javaclasspath ()
-## @deftypefnx {Function file} {[@var{static}, @var{dynamic}] =} javaclasspath ()
-## @deftypefnx {Function file} {@var{path} =} javaclasspath (@var{what})
-## Return the class path of the Java virtual machine in
-## the form of a cell array of strings. 
+## @deftypefn  {Function File} {} javaclasspath ()
+## @deftypefnx {Function File} {@var{dpath} =} javaclasspath ()
+## @deftypefnx {Function File} {[@var{dpath}, @var{spath}] =} javaclasspath ()
+## @deftypefnx {Function File} {@var{clspath} =} javaclasspath (@var{what})
+## Return the class path of the Java virtual machine in the form of a cell
+## array of strings. 
+##
+## If called with no inputs:
 ##
-## If called without input parameter:@*
 ## @itemize
-## @item If no output is requested, the result is simply printed 
-## on the standard output.
-## @item If one output value @var{STATIC} is requested, the result is
-## the static classpath.
-## @item If two output values@var{STATIC} and @var{DYNAMIC} are 
-## requested, the first variable will contain the static classpath,
-## the second will be filled with the dynamic classpath.
+## @item If no output is requested, the dynamic and static classpaths are printed 
+## to the standard output.
+##
+## @item If one output value @var{dpath} is requested, the result is
+## the dynamic classpath.
+##
+## @item If two output values@var{dpath} and @var{spath} are 
+## requested, the first variable will contain the dynamic classpath and
+## the second will be contain the static classpath.
 ## @end itemize
 ## 
-## If called with a single input parameter @var{what}:@*
-## @itemize
-## @item If @var{what} is @code{"-static"} return the static classpath
-## @item If @var{what} is @code{"-dynamic"} return the dynamic classpath
-## @item If @var{what} is @code{"-all"} return both the static and
-## dynamic classpath
-## @end itemize
+## If called with a single input parameter @var{what}:
+##
+## @table @asis
+## @item "-dynamic"
+## Return the dynamic classpath.
+##
+## @item "-static"
+## Return the static classpath.
+##
+## @item "-all"
+## Return both the static and dynamic classpath in a single cellstr.
+## @end table
 ## @seealso{javaaddpath, javarmpath}
 ## @end deftypefn
 
@@ -57,18 +65,18 @@
   static_path_list = strsplit (static_path, pathsep ());
   if (numel (static_path_list) > 1)
     ## remove first element (which is .../octave.jar)
-    static_path_list = static_path_list(2:numel (static_path_list));
+    static_path_list(1) = [];
   else
     static_path_list = {};
   endif
 
-  switch nargin
+  switch (nargin)
     case 0
-      switch nargout
+      switch (nargout)
         case 0
-          disp_path_list ( "STATIC", static_path_list )
+          disp_path_list ("STATIC", static_path_list)
           disp ("");
-          disp_path_list ( "DYNAMIC", dynamic_path_list )
+          disp_path_list ("DYNAMIC", dynamic_path_list)
 
         case 1
           varargout{1} = cellstr (dynamic_path_list);
@@ -79,12 +87,16 @@
       endswitch
         
     case 1
-      switch nargout
+      switch (nargout)
         case 0
-          if (strcmp (which, "-static") == 1)
-            disp_path_list ( "STATIC", static_path_list )
-          elseif (strcmp (which, "-dynamic") == 1)
-            disp_path_list ( "DYNAMIC", dynamic_path_list )
+          if (strcmp (which, "-static"))
+            disp_path_list ("STATIC", static_path_list)
+          elseif (strcmp (which, "-dynamic"))
+            disp_path_list ("DYNAMIC", dynamic_path_list)
+          elseif (strcmp (which, "-all") == 1)
+            disp_path_list ("STATIC", static_path_list)
+            disp ("");
+            disp_path_list ("DYNAMIC", dynamic_path_list)
           endif
 
         case 1
@@ -102,7 +114,7 @@
 
 ## Display cell array of paths
 
-function disp_path_list ( which, path_list )
+function disp_path_list (which, path_list)
   printf ("   %s JAVA PATH\n\n", which);
   if (numel (path_list) > 0)
     printf ("      %s\n", path_list{:});
@@ -110,3 +122,4 @@
     printf ("      - empty -\n");
   endif
 endfunction
+
diff --git a/scripts/java/javafields.m b/scripts/java/javafields.m
--- a/scripts/java/javafields.m
+++ b/scripts/java/javafields.m
@@ -17,30 +17,31 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function file} {@var{p} =} javafields (@var{class})
-## Return the fields of a Java object in the form of a cell 
+## @deftypefn  {Function File} {} javafields (@var{javaobj})
+## @deftypefnx {Function File} {} javafields ("@var{classname}")
+## @deftypefnx {Function File} {@var{fld_names} =} javafields (@dots{})
+## Return the fields of a Java object or Java class in the form of a cell 
 ## array of strings.  If no output is requested, print the result
-## printed on the standard output.
-## @seealso{javamethods}
+## to the standard output.
+## @seealso{javamethods, javaObject}
 ## @end deftypefn
 
-function retval = javafields (classname)
+function fld_names = javafields (javaobj)
   
   if (nargin != 1)
     print_usage ();
-  else
-    c_methods = java_invoke ("org.octave.ClassHelper", "getFields", classname);
-    method_list = strsplit (c_methods, ';');
+  endif
+  
+  c_methods = java_invoke ("org.octave.ClassHelper", "getFields", javaobj);
+  method_list = strsplit (c_methods, ';');
 
-    switch (nargout)
-      case 0
-        if (! isempty (method_list))
-          disp (method_list);
-        endif
-
-      case 1
-        retval = cellstr (method_list);
-   endswitch
- endif
+  if (nargout == 0)
+    if (! isempty (method_list))
+      disp (method_list);
+    endif
+  else
+    fld_names = cellstr (method_list);
+  endif
 
 endfunction
+
diff --git a/scripts/java/javamem.m b/scripts/java/javamem.m
--- a/scripts/java/javamem.m
+++ b/scripts/java/javamem.m
@@ -17,13 +17,13 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} javamem ()
-## @deftypefnx {Function File} [@var{jmem}] = javamem ()
-## Show current memory status of the Java virtual machine (JVM)
-## and run garbage collector.
+## @deftypefn  {Function File} {} javamem ()
+## @deftypefnx {Function File} {@var{jmem} =} javamem ()
+## Show the current memory usage of the Java virtual machine (JVM)
+## and run the garbage collector.
 ##
-## When no return argument is given the info is echoed to the screen.
-## Otherwise, output cell array @var{jmem} contains Maximum, Total,
+## When no return argument is given the info is printed to the screen.
+## Otherwise, the output cell array @var{jmem} contains Maximum, Total,
 ## and Free memory (in bytes).
 ##
 ## All Java-based routines are run in the JVM's shared memory pool,
@@ -31,25 +31,29 @@
 ## your computer's total memory (which comprises physical RAM and
 ## virtual memory / swap space on hard disk).
 ##
-## The maximum available memory can be set using the file java.opts
+## The maximum allowable memory usage can be set using the file java.opts
 ## (in the same subdirectory where javaaddpath.m lives, see 
-## "which javaaddpath". Usually that is: @*
-## [/usr]/share/octave/packages/java-<version>.
+## "which javaaddpath".  Usually that is:
+##
+## @file{OCTAVE_HOME/share/octave/OCTAVE_VERSION/m/java/}
 ##
-## java.opts is a plain text file, one option per line. The
+## java.opts is a plain text file with one option per line.  The
 ## default initial memory size and default maximum memory size (which
-## are both system dependent) can be overridden like so: @*
-## -Xms64m @*
-## -Xmx512m @*
+## are both system dependent) can be overridden like so:
+##
+## @nospell{-Xms64m}
+##
+## @nospell{-Xmx512m}
+##
 ## (in megabytes in this example.)
 ## You can adapt these values to your own requirements if your system
-## has limited available physical memory or when you get Java memory
+## has limited available physical memory or if you get Java memory
 ## errors.
 ##
 ## "Total memory" is what the operating system has currently assigned
 ## to the JVM and depends on actual and active memory usage.
-## "Free memory" is self-explanatory. During operation of Java-based
-## octave functions the amounts of Total and Free memory will vary,
+## "Free memory" is self-explanatory.  During operation of Java-based
+## Octave functions the amount of Total and Free memory will vary,
 ## due to Java's own cleaning up and your operating system's memory
 ## management.
 ## @end deftypefn
@@ -61,28 +65,29 @@
 ## 2010-08-25 Corrected text on java memory assignments
 ## 2010-09-05 Further overhauled help text
 
-function j_mem = javamem ()
+function jmem = javamem ()
 
   rt = java_invoke ("java.lang.Runtime", "getRuntime");
   rt.gc;
-  jmem = cell (3, 1);
-  jmem{1} = rt.maxMemory ().doubleValue ();
-  jmem{2} = rt.totalMemory ().doubleValue ();
-  jmem{3} = rt.freeMemory ().doubleValue ();
+  jvmem = cell (3, 1);
+  jvmem{1} = rt.maxMemory ().doubleValue ();
+  jvmem{2} = rt.totalMemory ().doubleValue ();
+  jvmem{3} = rt.freeMemory ().doubleValue ();
 
   if (nargout == 0)
     printf ("\nJava virtual machine (JVM) memory info:\n");
     printf ("Maximum available memory:        %5d MiB;\n",
-            jmem{1} / 1024 / 1024);
+            jvmem{1} / 1024 / 1024);
     printf ("   (...running garbage collector...)\n");
     printf ("OK, current status:\n");
     printf ("Total memory in virtual machine: %5d MiB;\n",
-            jmem{2} / 1024 / 1024);
+            jvmem{2} / 1024 / 1024);
     printf ("Free memory in virtual machine:  %5d MiB;\n",
-            jmem{3} / 1024 / 1024);
+            jvmem{3} / 1024 / 1024);
     printf ("%d CPUs available.\n", rt.availableProcessors ());
   else
-    j_mem = jmem;
+    jmem = jvmem;
   endif
 
 endfunction
+
diff --git a/scripts/java/javamethods.m b/scripts/java/javamethods.m
--- a/scripts/java/javamethods.m
+++ b/scripts/java/javamethods.m
@@ -17,29 +17,31 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function file} {@var{P} =} javamethods (@var{class})
-## Return the methods of a Java object in the form of a cell 
+## @deftypefn  {Function File} {} javamethods (@var{javaobj})
+## @deftypefnx {Function File} {} javamethods ("@var{classname}")
+## @deftypefnx {Function File} {@var{mtd_names} =} javamethods (@dots{})
+## Return the methods of a Java object or Java class in the form of a cell 
 ## array of strings.  If no output is requested, print the result to the
 ## standard output.
-## @seealso{methods}
+## @seealso{javafields, java_invoke, javaMethod, javaObject}
 ## @end deftypefn
 
-function retval = javamethods (classname)
+function mtd_names = javamethods (classname)
   
   if (nargin != 1)
     print_usage ();
-  else
-    c_methods = java_invoke ("org.octave.ClassHelper", "getMethods", classname);
-    method_list = strsplit (c_methods, ";");
+  endif
+
+  cls_methods = java_invoke ("org.octave.ClassHelper", "getMethods", classname);
+  method_list = strsplit (cls_methods, ';');
 
-    switch nargout
-      case 0
-        if (! isempty (method_list))
-          disp(method_list);
-        endif
-      case 1
-        retval = cellstr (method_list);
-    endswitch
+  if (nargout == 0)
+    if (! isempty (method_list))
+      disp (method_list);
+    endif
+  else
+    mtd_names = cellstr (method_list);
   endif
 
 endfunction
+
diff --git a/scripts/java/javarmpath.m b/scripts/java/javarmpath.m
--- a/scripts/java/javarmpath.m
+++ b/scripts/java/javarmpath.m
@@ -18,22 +18,31 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function file} {} javarmpath (@var{path})
-## Remove @var{path} from the dynamic class path of the Java virtual
-## machine.  @var{path} may be either a directory where @file{.class}
+## @deftypefn  {Function File} {} javarmpath (@var{clspath})
+## @deftypefnx {Function File} {} javarmpath (@var{clspath1}, @dots{})
+## Remove @var{clspath} from the dynamic class path of the Java virtual
+## machine.  @var{clspath} may either be a directory where @file{.class}
 ## files are found, or a @file{.jar} file containing Java classes.
+## Multiple paths may be removed at once by specifying additional arguments.
 ## @seealso{javaaddpath, javaclasspath}
 ## @end deftypefn
 
-function javarmpath (class_path)
+function javarmpath (varargin)
 
-  if (nargin != 1)
+  if (nargin < 1)
     print_usage ();
-  else
-    old_path = canonicalize_file_name (tilde_expand (class_path));
+  endif
+
+  for i = 1:numel (varargin)
+    clspath = varargin{i};
+    if (! ischar (clspath))
+      error ("javarmpath: CLSPATH must be a string");
+    endif
+
+    old_path = canonicalize_file_name (tilde_expand (clspath));
     if (exist (old_path, "dir"))
-      if (! strcmp (old_path (end), filesep))
-        old_path = [old_path, filesep];
+      if (old_path(end) != filesep ())
+        old_path = [old_path, filesep()];
       endif
     endif
 
@@ -43,6 +52,7 @@
     if (! success)
       warning ("javarmpath: %s: not found in Java classpath", old_path);
     endif
-  endif
+  endfor
 
 endfunction
+
diff --git a/scripts/java/listdlg.m b/scripts/java/listdlg.m
--- a/scripts/java/listdlg.m
+++ b/scripts/java/listdlg.m
@@ -17,7 +17,7 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function file} {[@var{sel}, @var{ok}] =} listdlg (@var{key}, @var{value}, @dots{})
+## @deftypefn {Function File} {[@var{sel}, @var{ok}] =} listdlg (@var{key}, @var{value}, @dots{})
 ## Return user inputs from a list dialog box in a vector of 
 ## selection indices @var{sel} and a flag @var{ok} indicating how the
 ## user closed the dialog box.  The value of @var{ok} is 1 if the user
@@ -34,48 +34,58 @@
 ## @table @code
 ## @item "ListString"
 ##    a cell array of strings comprising the content of the list.
+##
 ## @item "SelectionMode"
-##    can be either @code{"Single"} or @code{"Multiple"}.
+##    can be either @code{"Single"} or @code{"Multiple"} (default).
+##
 ## @item "ListSize"
 ##    a vector with two elements @var{width} and @var{height} defining
-##    the size of the list field in pixels.
+##    the size of the list field in pixels.  Default is [160 300].
+##
 ## @item "InitialValue"
-##    a vector containing 1-based indices of preselected elements.
+##    a vector containing 1-based indices of preselected elements.  Default
+##    is 1 (first item).
+##
 ## @item "Name"
-##    a string to be used as the dialog caption.
+##    a string to be used as the dialog caption.  Default is "".
+##
 ## @item "PromptString"
-##    a cell array of strings to be displayed above the list field.
+##    a cell array of strings to be displayed above the list field.  Default
+##    is @{@}.
+##
 ## @item "OKString"
-##    a string used to label the OK button.
+##    a string used to label the OK button.  Default is "OK".
+##
 ## @item "CancelString"
-##    a string used to label the Cancel button.
+##    a string used to label the Cancel button.  Default is "Cancel".
 ## @end table
 ##
 ## Example:
 ##
 ## @example
+## @group
 ## [sel, ok] = listdlg ("ListString", @{"An item", "another", "yet another"@}, "SelectionMode", "Multiple" );
 ## if (ok == 1)
-##    imax = numel (sel);
-##    for i = 1:1:imax
+##   imax = numel (sel);
+##   for i = 1:1:imax
 ##     disp (sel(i));
-##    end
-## end
+##   endfor
+## endif
+## @end group
 ## @end example
 ##
-## @seealso{errordlg, helpdlg, inputdlg, questdlg, warndlg}
+## @seealso{errordlg, helpdlg, inputdlg, msgbox, questdlg, warndlg}
 ## @end deftypefn
 
 function varargout = listdlg (varargin)
 
-   if nargin < 2
+   if (nargin < 2)
      print_usage ();
-     return;
-   end
+   endif
    
    listcell = {""};
-   selmode = "single";
-   listsize = [300, 160];
+   selmode = "multiple";
+   listsize = [160, 300];
    initialvalue = 1;
    name = "";
    prompt = {""};
@@ -106,7 +116,7 @@
    ## make sure prompt strings are a cell array
    if (! iscell (prompt))
      prompt = {prompt};
-   end
+   endif
 
    ## make sure listcell strings are a cell array
    if (! iscell (listcell))
@@ -128,3 +138,4 @@
    endif
 
 endfunction
+
diff --git a/scripts/java/msgbox.m b/scripts/java/msgbox.m
--- a/scripts/java/msgbox.m
+++ b/scripts/java/msgbox.m
@@ -17,59 +17,59 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function file} {@var{p} =} msgbox (@var{msg}, @var{title}, @var{ICON})
-## Display @var{msg} using a message dialog. 
+## @deftypefn  {Function File} {@var{h} =} msgbox (@var{msg})
+## @deftypefnx {Function File} {@var{h} =} msgbox (@var{msg}, @var{title})
+## @deftypefnx {Function File} {@var{h} =} msgbox (@var{msg}, @var{title}, @var{icon})
+## Display @var{msg} using a message dialog box. 
 ##
 ## The message may have multiple lines separated by newline characters
 ## (@code{"\n"}), or it may be a cellstr array with one element for each
-## line.  The optional @var{title} (character string) can be used to
+## line.  The optional input @var{title} (character string) can be used to
 ## decorate the dialog caption.
 ##
 ## The optional argument @var{icon} selects a dialog icon. 
-## It can be one of @code{"error"}, @code{"help"} or @code{"warn"}.
+## It can be one of @code{"none"} (default), @code{"error"}, @code{"help"} or
+## @code{"warn"}.
 ##
 ## The return value is always 1.
-## @seealso{helpdlg, questdlg, warndlg}
+## @seealso{errordlg, helpdlg, inputdlg, listdlg, questdlg, warndlg}
 ## @end deftypefn
 
-function retval = msgbox (message, varargin)
+function h = msgbox (msg, title = "", icon)
+
+  if (nargin < 1 || nargin > 3)
+    print_usage ();
+  endif
 
-  if (! ischar (message))
-    if (iscell (message))
-      message = cell2mlstr (message);
+  if (! ischar (msg))
+    if (iscell (msg))
+      msg = cell2mlstr (msg);
     else
-      error ("msgbox: character string or cellstr array expected for message");
+      error ("msgbox: MSG must be a character string or cellstr array");
     endif
   endif
+
+  if (! ischar (title))
+    error ("msgbox: TITLE must be a character string");
+  endif
   
-  switch (numel (varargin))
-    case 0
-      title = "";
-      dlg = "emptydlg";
-
-    case 1
-      title = varargin{1};
-      dlg = "emptydlg";
-
-    otherwise
-      ## two or more arguments
-      title = varargin{1};
-      icon =  varargin{2};
-      if (strcmp (icon, "error"))
+  dlg = "emptydlg";
+  if (nargin == 3)
+    switch (icon)
+      case "error"
         dlg = "errordlg";
-      elseif (strcmp (icon, "help"))
+      case "help"
         dlg = "helpdlg";
-      elseif (strcmp (icon, "warn"))
+      case "warn"
         dlg = "warndlg";
-      else
+      case "none"
         dlg = "emptydlg";
-      end
-  endswitch
-
-  if (! ischar (title))
-    error ("msgbox: character string expected for title");
+      otherwise
+        error ("msgbox: ICON is not a valid type");
+    endswitch
   endif
 
-  retval = java_invoke ("org.octave.JDialogBox", dlg, message, title );
+  h = java_invoke ("org.octave.JDialogBox", dlg, msg, title);
 
 endfunction
+
diff --git a/scripts/java/questdlg.m b/scripts/java/questdlg.m
--- a/scripts/java/questdlg.m
+++ b/scripts/java/questdlg.m
@@ -17,14 +17,15 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function file} {@var{p} =} questdlg (@var{msg}, @var{title})
-## @deftypefnx {Function file} @var{p} = questdlg (@var{msg}, @var{title}, @var{default})
-## @deftypefnx {Function file} @var{p} = questdlg (@var{msg}, @var{title}, @var{btn1}, @var{btn2}, @var{default})
-## @deftypefnx {Function file} @var{p} = questdlg (@var{msg}, @var{title}, @var{btn1}, @var{btn2}, @var{btn3}, @var{default})
+## @deftypefn  {Function File} {@var{btn} =} questdlg (@var{msg})
+## @deftypefnx {Function File} {@var{btn} =} questdlg (@var{msg}, @var{title})
+## @deftypefnx {Function File} {@var{btn} =} questdlg (@var{msg}, @var{title}, @var{default})
+## @deftypefnx {Function File} {@var{btn} =} questdlg (@var{msg}, @var{title}, @var{btn1}, @var{btn2}, @var{default})
+## @deftypefnx {Function File} {@var{btn} =} questdlg (@var{msg}, @var{title}, @var{btn1}, @var{btn2}, @var{btn3}, @var{default})
 ## Display @var{msg} using a question dialog box and return the caption
 ## of the activated button.
 ##
-## The dialog may contain two or three buttons which all close the dialog. 
+## The dialog may contain two or three buttons which will all close the dialog.
 ##
 ## The message may have multiple lines separated by newline characters
 ## (@code{"\n"}), or it may be a cellstr array with one element for each
@@ -32,74 +33,67 @@
 ## decorate the dialog caption.
 ##
 ## The string @var{default} identifies the default button, 
-## which is activated by pressing the ENTER key.
+## which is activated by pressing the @kbd{ENTER} key.
 ## It must match one of the strings given in @var{btn1}, @var{btn2} or
 ## @var{btn3}.
 ##
 ## If only @var{msg} and @var{title} are specified, three buttons with
-## the default captions @code{"Yes"}, @code{"No"}, and @code{"Cancel"}
-## are used.
+## the default captions "Yes", "No", and "Cancel" are used.
 ##
-## If only two button captions @var{btn1} and @var{btn2} are specified, 
+## If only two button captions, @var{btn1} and @var{btn2}, are specified 
 ## the dialog will have only these two buttons.
 ##
 ## @seealso{errordlg, helpdlg, inputdlg, listdlg, warndlg}
 ## @end deftypefn
 
-function ret = questdlg (question, varargin)
+function btn = questdlg (msg, title = "Question Dialog", varargin)
 
-  if (numel (varargin) < 1)
+  if (nargin < 1 || nargin > 6)
     print_usage ();
   endif
   
-  options{1} = "Yes";      ## button1
-  options{2} = "No";       ## button2
-  options{3} = "Cancel";   ## button3
-  options{4} = "Yes";      ## default
-
-  if (! ischar (question))
-    if (iscell (question))
-      question = cell2mlstr (question);
+  if (! ischar (msg))
+    if (iscell (msg))
+      msg = cell2mlstr (msg);
     else
-      error ("questdlg: character string or cellstr array expected for message");
+      error ("questdlg: MSG must be a character string or cellstr array");
     endif
   endif
 
+  if (! ischar (title))
+    error ("questdlg: TITLES must be a character string");
+  endif
+
+  options{1} = "Yes";      # button1
+  options{2} = "No";       # button2
+  options{3} = "Cancel";   # button3
+  options{4} = "Yes";      # default
+
   switch (numel (varargin))
     case 1
-      ## title was given
-      title = varargin{1};
+      ## default button string
+      options{4} = varargin{1};  # default
 
-    case 2
-      ## title and default button string
-      title = varargin{1};
-      options{4} = varargin{2}; ## default
+    case 3
+      ## two buttons and default button string
+      options{1} = varargin{1};  # button1
+      options{2} = "";           # not used, no middle button
+      options{3} = varargin{2};  # button3
+      options{4} = varargin{3};  # default
 
     case 4
-      ## title, two buttons and default button string
-      title = varargin{1};
-      options{1} = varargin{2}; ## button1
-      options{2} = "";          ## not used, no middle button
-      options{3} = varargin{3}; ## button3
-      options{4} = varargin{4}; ## default
-
-    case 5
-      ## title, three buttons and default button string
-      title      = varargin{1};
-      options{1} = varargin{2}; ## button1
-      options{2} = varargin{3}; ## button2
-      options{3} = varargin{4}; ## button3
-      options{4} = varargin{5}; ## default
+      ## three buttons and default button string
+      options{1} = varargin{1};  # button1
+      options{2} = varargin{2};  # button2
+      options{3} = varargin{3};  # button3
+      options{4} = varargin{4};  # default
 
     otherwise
       print_usage ();
+
   endswitch
 
-  if (! ischar (title))
-    error ("questdlg: character string expected for title");
-  endif
-
-  ret = java_invoke ("org.octave.JDialogBox", "questdlg", question,
+  btn = java_invoke ("org.octave.JDialogBox", "questdlg", msg,
                      title, options);
 
 endfunction
diff --git a/scripts/java/warndlg.m b/scripts/java/warndlg.m
--- a/scripts/java/warndlg.m
+++ b/scripts/java/warndlg.m
@@ -17,39 +17,37 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function file} {@var{p} =} warndlg (@var{msg}, @var{title})
+## @deftypefn  {Function File} {@var{h} =} warndlg (@var{msg})
+## @deftypefnx {Function File} {@var{h} =} warndlg (@var{msg}, @var{title})
 ## Display @var{msg} using a warning dialog box. 
 ##
 ## The message may have multiple lines separated by newline characters
-## (@code{"\n"}), or it may be a cellstr array with one element for each
-## line.  The optional @var{title} (character string) can be used to
-## decorate the dialog caption.
+## ("\n"), or it may be a cellstr array with one element for each
+## line.  The optional input @var{title} (character string) can be used to
+## set the dialog caption.  The default title is "Warning Dialog".
 ##
 ## @seealso{helpdlg, inputdlg, listdlg, questdlg}
 ## @end deftypefn
 
-function retval = warndlg (message, varargin)
+function retval = warndlg (msg, title = "Warning Dialog")
+
+  if (nargin < 1 || nargin > 2)
+    print_usage ();
+  endif
 
-  if (! ischar (message))
-    if (iscell (message))
-      message = cell2mlstr (message);
+  if (! ischar (msg))
+    if (iscell (msg))
+      msg = cell2mlstr (msg);
     else
-      error ("warndlg: character string or cellstr array expected for message");
+      error ("warndlg: MSG must be a string or cellstr array");
     endif
   endif
-  
-  switch (numel (varargin))
-    case 0
-      title = "Warning Dialog";
 
-    otherwise
-      if (ischar (varargin{1}))
-        title = varargin{1};
-      else
-        error ("warndlg: character string expected for title");
-      endif
-  endswitch
+  if (! ischar (title))
+    error ("warndlg: TITLE must be a character string");
+  endif
 
-  retval = java_invoke ("org.octave.JDialogBox", "warndlg", message, title);
+  retval = java_invoke ("org.octave.JDialogBox", "warndlg", msg, title);
 
 endfunction
+