# HG changeset patch
# User Ernst Reissner <rei3ner@arcor.de>
# Date 1470919985 -7200
#      Thu Aug 11 14:53:05 2016 +0200
# Node ID 021640103c8943ec76affe2ce801a5450d58291e
# Parent  eea02e17c6b8a0b1fe01e4981eba1b6c2eda8371
mainly reformatting.

diff -r eea02e17c6b8 -r 021640103c89 scripts/java/org/octave/ClassHelper.java
--- a/scripts/java/org/octave/ClassHelper.java	Thu Aug 11 14:42:21 2016 +0200
+++ b/scripts/java/org/octave/ClassHelper.java	Thu Aug 11 14:53:05 2016 +0200
@@ -33,7 +33,7 @@
 import java.lang.reflect.Constructor;
 import java.lang.reflect.Array;
 import java.lang.reflect.InvocationTargetException;
-import java.lang.reflect.Modifier;
+//import java.lang.reflect.Modifier;
 
 //! Collection of methods being the core of the octave functions
 //! forming Octave's Java Interface.
@@ -77,8 +77,8 @@
 //! used by @file javaArray.m defining @c javaArray.
 public class ClassHelper
 {
-  //! The loader for the dynamic classpath 
-  //! delegating to the loader for the static classpath. 
+  //! The loader for the dynamic classpath
+  //! delegating to the loader for the static classpath.
   private static OctClassLoader loader;
 
   static
@@ -91,23 +91,23 @@
   //! with the former classloader as parent.
   private static OctClassLoader octClsLoader() {
     ClassLoader l = ClassHelper.class.getClassLoader ();
-    return l instanceof OctClassLoader 
-      ? (OctClassLoader) l 
+    return l instanceof OctClassLoader
+      ? (OctClassLoader) l
       : new OctClassLoader (l);
   }
 
   //! Add the given path @c path to the (dynamic) classpath.
   //! Used by @file javaaddpath.m only.
   //!
-  //! @param path 
+  //! @param path
   //!    path to add to the classpath.
   //!    This could be e.g. (examples for Unix)
   //!    <code>/home/charles</code>, <code>~/Octave</code>
   //!    or <code>../Software</code>.
-  //! @return 
+  //! @return
   //!    whether the given path exists and was thus added to the classpath.
   //! @throws MalformedURLException
-  //!    if conversion from URI representing @c path to URL fails. 
+  //!    if conversion from URI representing @c path to URL fails.
   //!    This should not occur if @c path points to a file.
   public static boolean addClassPath (String path)
     throws MalformedURLException
@@ -115,7 +115,6 @@
     File f = new File (path);
     if (f.exists ())
       {
-//        loader.addClassPath (path);
         // file2url may throw MalformedURLException
         loader.addURL (file2url(f));
         return true;
@@ -134,7 +133,7 @@
   //! @throws MalformedURLException
   //!    if conversion from URI representing @c path to URL fails.
   //!    This should not occur if @c path points to a file.
-    public static boolean removeClassPath (String path)
+  public static boolean removeClassPath (String path)
     throws MalformedURLException
   {
     boolean found = false;
@@ -163,7 +162,7 @@
             // path to be re-added
             loader.addURL (url);
           }
-       }
+      }
 
     return found;
   }
@@ -238,7 +237,6 @@
     return file.toURI ().toURL ();
   }
 
-
   // new -MH-
   //! Return a list of public methods
   //! of the class with the given class name @c classname
@@ -256,11 +254,10 @@
     throws ClassNotFoundException
   {
     return getMethods (Class.forName (classname));
-    // FIXME: ****
+    // FIXME: missing involving OctClassloader
     //return getMethods (Class.forName (classname, true, loader));
   }
 
-
   // new -MH-
   //! Return a list of public methods
   //! of the class of the instance @c obj.
@@ -278,7 +275,6 @@
     return getMethods (obj.getClass ());
   }
 
-
   // new -MH-
   //! Return list of public
   //! methods for given class @c klass.
@@ -290,7 +286,7 @@
   //! @param klass
   //!    the class under consideration.
   //! @return
-  //!    the list of methods for given class @c klass as a string, 
+  //!    the list of methods for given class @c klass as a string,
   //!    the signatures of the methods separated by <code>;</code>.
   public static String getMethods (Class klass)
   {
@@ -304,12 +300,12 @@
             sb.append (';');
           }
 
-        // Return type and name 
+        // Return type and name
         sb.append (theMethod[i].getReturnType ().getCanonicalName ());
         sb.append (' ');
         sb.append (theMethod[i].getName ());
 
-        // parameter list 
+        // parameter list
         sb.append ('(');
         Class theParameter[] = theMethod[i].getParameterTypes ();
         for (int j = 0; j < theParameter.length; j++)
@@ -322,13 +318,13 @@
           }
         sb.append (')');
 
-        // exceptions 
+        // exceptions
         Class theExceptions[] = theMethod[i].getExceptionTypes ();
         if (theExceptions.length > 0)
           {
             sb.append (" throws ");
             sb.append (theExceptions[0].getCanonicalName ());
-             for (int j = 1; j < theExceptions.length; j++)
+            for (int j = 1; j < theExceptions.length; j++)
               {
                 sb.append (", ");
                 sb.append (theExceptions[j].getCanonicalName ());
@@ -339,7 +335,6 @@
     return sb.toString ();
   }
 
-
   // new -MH-
   //! Return a list of all accessible public fields
   //! of the given class @c klass.
@@ -350,7 +345,7 @@
   //!
   //! @param klass
   //!    the class under consideration.
-  //! @return 
+  //! @return
   //!    the list of names of accessible public fields
   //!    of the given class @c klass
   //!    as a string, separated by <code>;</code>.
@@ -371,7 +366,6 @@
     return sb.toString ();
   }
 
-
   // new -MH-
   //! Return a list of all accessible public fields
   //! of the class with the given class name @c classname
@@ -389,10 +383,10 @@
     throws ClassNotFoundException
   {
     return getFields (Class.forName (classname));
-//    return getFields (Class.forName (classname, true, loader));
+    // FIXME: should involve OctClassLoader
+    //    return getFields (Class.forName (classname, true, loader));
   }
 
-
   // new -MH-
   //! Return a list of all accessible public fields
   //! of class of the instance @c obj.
@@ -448,6 +442,7 @@
                 return m;
               }
           }
+
         return null;
       }
   }
@@ -476,11 +471,9 @@
     catch (NoSuchMethodException e)
       {
         Constructor[] cList = cls.getConstructors ();
-        //System.out.println("# constructors: " + cList.length);
         Constructor c;
         for (int i = 0; i < cList.length; i++)
           {
-            //System.out.println("Considering constructor: " + cList[i]);
             c = cList[i];
             if (c.getParameterTypes ().length == argTypes.length
                 && isCallableFrom (c, argTypes))
@@ -492,7 +485,7 @@
       }
   }
 
-  //! Invoke method @c mthd on the object @c target with arguments @c args. 
+  //! Invoke method @c mthd on the object @c target with arguments @c args.
   //!
   //! @param mthd
   //!    the method to be invoked.
@@ -519,71 +512,69 @@
   private static Object invokeMethod (Method mthd, Object target, Object[] args)
     throws InvocationTargetException, IllegalAccessException
   {
-    //if (Modifier.isPublic(mthd.getModifiers()))
-    try 
+    // FIXME: maybe the following is a better solution: 
+    // if (Modifier.isPublic(mthd.getModifiers()))...
+    try
       {
-        // may throw InvocationTargetException, 
+        // may throw InvocationTargetException,
         // but no IllegalAccessException
         return mthd.invoke (target, args);
       }
     catch (IllegalAccessException ex)
       {
-        // FIXME: is this really wanted? 
+        // FIXME: is this really wanted?
         String mName   = mthd.getName ();
         Class[] pTypes = mthd.getParameterTypes ();
  
-        // search in target class and in superclasses. 
+        // search in target class and in superclasses.
         for (Class currClass = target.getClass ();
-             currClass != null; 
+             currClass != null;
              currClass = currClass.getSuperclass ())
           {
             try
               {
-                //  may throw NoSuchMethodException
+                // may throw NoSuchMethodException
                 Method meth = currClass.getMethod (mName, pTypes);
                 if (!meth.equals (mthd))
                   {
-                    // may throw InvocationTargetException, 
+                    // may throw InvocationTargetException,
                     // IllegalAccessException
                     return meth.invoke (target, args);
                   }
               }
-            catch (NoSuchMethodException ex2) // NOPMD
+            catch (NoSuchMethodException ex2) // NOPMD: rulecheck suspended
               {
-                // empty catch is really ok: just go on searching 
+                // empty catch is really ok: just go on searching
               }
 
-            // FIXME: I am pretty sure, that this finds no further methods 
-            // and shall thus be removed (ER). 
+            // FIXME: I am pretty sure, that this finds no further methods
+            // and shall thus be removed (ER).
             Class[] ifaceList = currClass.getInterfaces ();
             for (int i = 0; i < ifaceList.length; i++)
               {
                 try
                   {
-                    //  may throw NoSuchMethodException
+                    // may throw NoSuchMethodException
                     Method meth = ifaceList[i].getMethod (mName, pTypes);
                     // may throw InvocationTargetException
                     return meth.invoke (target, args);
                   }
-                catch (NoSuchMethodException ex2) // NOPMD
+                catch (NoSuchMethodException ex2) // NOPMD: rulecheck suspended
                   {
-                    // empty catch is really ok: just go on searching 
+                    // empty catch is really ok: just go on searching
                   }
-              } // for 
-          } // for 
-        // throws IllegalAccessException 
+              }
+          }
+        // throws IllegalAccessException
         throw ex;
-     } // catch IllegalAccessException 
+      } // catch IllegalAccessException
   }
 
-
-  // Used internally and by 
-  // #do_javaMethod(void*, std::string&, octave_value_list&) 
-  // in <code>ov-java.cc</code> only. 
+  // Used internally and by
+  // #do_javaMethod(void*, std::string&, octave_value_list&)
+  // in <code>ov-java.cc</code> only.
   // getField(Object, String)
-  public static Object invokeMethod (Object target, 
-                                     String name,
-                                     Object[] args, 
+  public static Object invokeMethod (Object target, String name, Object[] args,
                                      Class[] argTypes)
     throws Throwable
   {
@@ -607,22 +598,17 @@
 
   }
 
-  // using loader 
-  // Used internally and by @file ov-java.cc only. 
+  // using loader
+  // Used internally and by @file ov-java.cc only.
   // getStaticField(String, String)
-  public static Object invokeStaticMethod (String cls, 
-                                           String name,
-                                           Object[] args, 
-                                           Class[] argTypes)
-    throws ClassNotFoundException, 
-    NoSuchMethodException, 
-    IllegalAccessException, 
-    Throwable
+  public static Object invokeStaticMethod (String cls, String name, 
+                                           Object[] args, Class[] argTypes)
+    throws ClassNotFoundException, NoSuchMethodException,
+    IllegalAccessException, Throwable
   {
-    // forName may throw ClassNotFoundException 
+    // forName may throw ClassNotFoundException
     Method m = findMethod (Class.forName (cls, true, loader), 
-                           name,
-                           argTypes);
+                           name, argTypes);
     if (m == null)
       {
         throw new NoSuchMethodException (name);
@@ -638,15 +624,14 @@
       }
     catch (InvocationTargetException ex)
       {
-        // may throw general Throwable 
+        // may throw general Throwable
         throw ex.getCause ();
       }
   }
 
-  // using loader 
-  // Used @file ov-java.cc only. 
-  public static Object invokeConstructor (String cls, 
-                                          Object[] args,
+  // using loader
+  // Used @file ov-java.cc only.
+  public static Object invokeConstructor (String cls, Object[] args,
                                           Class[] argTypes)
     throws Throwable
   {
@@ -676,18 +661,18 @@
   //! @param target
   //!    an object to query a field which shall not be @c null.
   //! @param name
-  //!    the name of the field of @c target 
-  //!    which shall not be @c null. 
-  //! @throws NoSuchFieldException 
+  //!    the name of the field of @c target
+  //!    which shall not be @c null.
+  //! @throws NoSuchFieldException
   //!    if @c target has no field with the given name.
   //! @throws IllegalAccessException
-  //!    if the field @c name of object @c target is not accessible. 
+  //!    if the field @c name of object @c target is not accessible.
   public static Object getField (Object target, String name)
     throws NoSuchFieldException, IllegalAccessException, Throwable
   {
     try
       {
-        // getField may throw NoSuchFieldException 
+        // getField may throw NoSuchFieldException
         //   if a field with the specified name is not found.
         // get may throw IllegalAccessException
         return target.getClass ().getField (name).get (target);
@@ -696,7 +681,7 @@
       {
         try
           {
-            // may throw Throwable if so does method name() 
+            // may throw Throwable if so does method name()
             return invokeMethod (target, name, new Object[0], new Class[0]);
           }
         catch (NoSuchMethodException ex2)
@@ -706,24 +691,22 @@
       }
   }
 
-  // based on loader 
-  // Used by @file ov-java.cc only. 
+  // based on loader
+  // Used by @file ov-java.cc only.
   public static Object getStaticField (String cls, String name)
-    throws ClassNotFoundException, 
-    NoSuchFieldException, 
-    IllegalAccessException, 
-    Throwable
+    throws ClassNotFoundException, NoSuchFieldException, 
+    IllegalAccessException, Throwable
   {
     try
       {
-        // getField may throw NoSuchFieldException 
+        // getField may throw NoSuchFieldException
         //   if a field with the specified name is not found.
         // get may throw IllegalAccessException
         return Class.forName (cls, true, loader).getField (name).get (null);
       }
     catch (NoSuchFieldException ex)
       {
-        // FIXME: is this really appropriate? 
+        // FIXME: is this really appropriate?
         try
           {
             return invokeStaticMethod (cls, name, new Object[0], new Class[0]);
@@ -735,29 +718,28 @@
       }
   }
 
-  // Used by @file ov-java.cc only. 
+  // Used by @file ov-java.cc only.
   public static void setField (Object target, String name, Object value)
     throws NoSuchFieldException, IllegalAccessException
   {
     // getField may throw NoSuchFieldException
     Field f = target.getClass ().getField (name);
-    // set may throw IllegalAccessException 
+    // set may throw IllegalAccessException
     f.set (target, castArgument (value, value.getClass (), f.getType ()));
   }
 
-  // based on loader 
-  // Used by @file ov-java.cc only. 
+  // based on loader
+  // Used by @file ov-java.cc only.
   public static void setStaticField (String cls, String name, Object value)
     throws ClassNotFoundException, NoSuchFieldException, IllegalAccessException
   {
-    // forName may throw ClassNotFoundException 
+    // forName may throw ClassNotFoundException
     // getField may throw NoSuchFieldException
     Field f = Class.forName (cls, true, loader).getField (name);
-    // set may throw IllegalAccessException 
+    // set may throw IllegalAccessException
     f.set (null, castArgument (value, value.getClass (), f.getType ()));
   }
 
-
   private static boolean isCallableFrom (Method m, Class[] argTypes)
   {
     Class[] expTypes = m.getParameterTypes ();
@@ -771,7 +753,6 @@
     return true;
   }
 
-
   private static boolean isCallableFrom (Constructor c, Class[] argTypes)
   {
     Class[] expTypes = c.getParameterTypes ();
@@ -785,10 +766,8 @@
     return true;
   }
 
-
   private static boolean isCallableFrom (Class expCls, Class argCls)
   {
-    //System.out.println("isCallableFrom: "+expCls.getCanonicalName() + " <=? " + argCls.getCanonicalName());
     if (argCls == null)
       {
         return !expCls.isPrimitive ();
@@ -800,12 +779,12 @@
       }
 
     if ((isNumberClass (expCls) || isBooleanClass (expCls))
-             && isNumberClass (argCls))
+        && isNumberClass (argCls))
       {
         return true;
       }
 
-   if (isCharClass (expCls) && argCls.equals (Character.class))
+    if (isCharClass (expCls) && argCls.equals (Character.class))
       {
         /*
           modified into a more strict check to avoid char to string matching
@@ -831,20 +810,18 @@
       }
 
     if (expCls.isArray () && argCls.isArray ()
-             && isCallableFrom (expCls.getComponentType (),
-                                argCls.getComponentType ()))
+        && isCallableFrom (expCls.getComponentType (),
+                           argCls.getComponentType ()))
       {
         return true;
       }
-    
+
     return expCls.equals (Object.class) && argCls.isPrimitive ();
-
   }
 
-
   private static boolean isNumberClass (Class cls)
   {
-    // FIXME: seems as if Byte is missing. 
+    // FIXME: seems as if Byte is missing.
     return cls.equals (Short.TYPE  ) || cls.equals (Short.class  )
       ||   cls.equals (Integer.TYPE) || cls.equals (Integer.class)
       ||   cls.equals (Long.TYPE   ) || cls.equals (Long.class   )
@@ -852,34 +829,17 @@
       ||   cls.equals (Double.TYPE ) || cls.equals (Double.class );
   }
 
-
   private static boolean isBooleanClass (Class cls)
   {
     return cls.equals (Boolean.class) || cls.equals (Boolean.TYPE);
   }
 
-
   private static boolean isCharClass (Class cls)
   {
     return cls.equals (Character.class) || cls.equals (Character.TYPE);
   }
 
-
-  //   //  * Check whether the supplied class is a String class.
-  //  *
-  //  * Added for more strict char/string matching of method signatures
-  //  * Date: 28-08-2010
-  //  * Author: Martin Hepperle
-  //  * @param cls Class - the class to check
-  //  * @return boolean - true if clas is of class java.lang.String
-  //   // private static boolean isStringClass (Class cls)
-  // {
-  //   return cls.equals (String.class);
-  // }
-
-
-  private static Object[] castArguments (Object[] args, 
-                                         Class[] argTypes,
+  private static Object[] castArguments (Object[] args, Class[] argTypes,
                                          Class[] expTypes)
   {
     for (int i = 0; i < args.length; i++)
@@ -889,8 +849,8 @@
     return args;
   }
 
-  // FIXME: simply null if no success. 
-  // To be analyzed: isn't type just obj.getClass()? 
+  // FIXME: simply null if no success.
+  // To be analyzed: isn't type just obj.getClass()?
   private static Object castArgument (Object obj, Class type, Class expType)
   {
     if (type == null || expType.isAssignableFrom (type))
@@ -900,8 +860,8 @@
     if (isNumberClass (expType))
       {
         Number num = (Number)obj;
-        // FIXME: what if obj is null? 
-        // FIXME: seems as if Byte is missing as in isNumberClass 
+        // FIXME: what if obj is null?
+        // FIXME: seems as if Byte is missing as in isNumberClass
         if (expType.equals (Short.TYPE) || expType.equals (Short.class))
           {
             return Short  .valueOf(num. shortValue());
@@ -923,17 +883,17 @@
             return Double .valueOf(num.doubleValue());
           }
         throw new IllegalStateException
-          ("Missing branch for byte? found "+expType);
+          ("Missing branch for byte? found " + expType);
       }
     if (isBooleanClass (expType))
       {
-        // FIXME: what if obj is null? 
-        // FIXME: why is obj a Number here?? 
+        // FIXME: what if obj is null?
+        // FIXME: why is obj a Number here??
         return Boolean.valueOf(((Number) obj).intValue () != 0);
       }
     if (isCharClass (expType))
       {
-        // FIXME: what if obj is null? 
+        // FIXME: what if obj is null?
         String s = obj.toString ();
         if (s.length () != 1)
           {
@@ -944,7 +904,7 @@
     if (expType.isArray () && type.isArray ())
       {
         // ensure that cast allows obj==null
-        return castArray (obj, 
+        return castArray (obj,
                           type   .getComponentType (),
                           expType.getComponentType ());
       }
@@ -967,8 +927,7 @@
   //!    the target class to cast the entries of @c obj.
   //! @throws IllegalArgumentException
   //!    if obj is no array instance.
-  private static Object castArray (Object obj, 
-                                   Class elemType,
+  private static Object castArray (Object obj, Class elemType,
                                    Class elemExpType)
   {
     // throws IllegalArgumentException if obj is not an array instance
@@ -982,54 +941,31 @@
     return result;
   }
 
-
-  //! Return the mathematical dimension of @c cls. 
-  //! This is 0 if @c cls no array type or if @c null. 
+  //! Return the mathematical dimension of @c cls.
+  //! This is 0 if @c cls no array type or if @c null.
   private static int getArrayClassNDims (Class cls)
   {
     int res = 0;
-    while (cls != null && cls.isArray ()) 
+    while (cls != null && cls.isArray ())
       {
         res++;
         cls = cls.getComponentType ();
       }
     return res;
-
-    // if (cls != null && cls.isArray ())
-    //   {
-    //     return (1 + getArrayClassNDims (cls.getComponentType ()));
-    //   }
-    // else
-    //   {
-    //     return 0;
-    //   }
   }
 
-  //! Return the innermost component type of @c cls. 
+  //! Return the innermost component type of @c cls.
   private static Class getArrayElemClass (Class cls)
   {
 
-    while (cls.isArray ()) 
+    while (cls.isArray ())
       {
         cls = cls.getComponentType ();
       }
     return cls;
-
-
-    // if (cls.isArray ())
-    //   {
-    //     return getArrayElemClass (cls.getComponentType ());
-    //   }
-    // else
-    //   {
-    //     return cls;
-    //   }
   }
 
-
-  private static Object getArrayElements (Object array, 
-                                          int[][] idx,
-                                          int offset,
+  private static Object getArrayElements (Object array, int[][] idx, int offset,
                                           int ndims, Class elemType)
   {
     if (offset >= ndims)
@@ -1052,14 +988,14 @@
         Array.set (retval, i, elem);
       }
     return retval;
-
   }
 
-  // Used by 
-  // #get_array_elements(JNIEnv*, jobject, octave_value_list&) 
-  // in @file ov-java.cc only and is recursive. 
-  //PMD: has an NPath complexity of 582
-  public static Object arraySubsref (Object obj, int[][] idx) // NOPMD
+  // Used by
+  // #get_array_elements(JNIEnv*, jobject, octave_value_list&)
+  // in @file ov-java.cc only and is recursive.
+  // PMD detects: has an NPath complexity of 582
+  public static Object arraySubsref (Object obj, 
+                                     int[][] idx) // NOPMD: rulecheck suspended
   {
     if (!obj.getClass ().isArray ())
       {
@@ -1085,7 +1021,6 @@
           }
       }
 
-
     int[] dims = new int[idx.length];
     for (int i = 0; i < idx.length; i++)
       {
@@ -1140,15 +1075,10 @@
       }
 
     return retval;
-
   }
 
-
-  private static Object setArrayElements (Object array,
-                                          int[][] idx,
-                                          int offset, 
-                                          int ndims, 
-                                          Object rhs)
+  private static Object setArrayElements (Object array, int[][] idx,
+                                          int offset, int ndims, Object rhs)
   {
     if (offset >= ndims)
       {
@@ -1179,12 +1109,11 @@
     return array;
   }
 
-  // PMD: has an NPath complexity of 294
+  // PMD detects: has an NPath complexity of 294
   // return value seems superfluous. 
   // Used by @file ov-java.cc only and is recursive. 
-  public static Object arraySubsasgn (Object obj, // NOPMD
-                                      int[][] idx, 
-                                      Object rhs) 
+  public static Object arraySubsasgn (Object obj, int[][] idx, 
+                                      Object rhs)// NOPMD: rulecheck suspended
   {
     if (!obj.getClass ().isArray ())
       {
@@ -1195,21 +1124,20 @@
       {
         if (idx[0].length == 1)
           {
-            // throws IllegalArgumentException if obj is not an array 
+            // throws IllegalArgumentException if obj is not an array
             Array.set (obj, idx[0][0], rhs);
           }
         else
           {
             for (int i = 0; i < idx[0].length; i++)
               {
-                // throws IllegalArgumentException if obj is not an array 
+                // throws IllegalArgumentException if obj is not an array
                 Array.set (obj, idx[0][i], Array.get (rhs, i));
               }
           }
         return obj;
       }
 
-
     int[] dims = new int[idx.length];
     for (int i = 0; i < idx.length; i++)
       {
@@ -1257,7 +1185,16 @@
   //! with dimensions given by @c dims.
   //! The class may be given directly as a @ref Class object
   //! or as a string via its name.
-  //! Used by @c javaArray only.
+  //! Used by @file javaArray.m defining @c javaArray only.
+  //!
+  //! Note that if you invoke <code>javaArray('java.lang.Object', 1)</code>,
+  //! this is translated into invocation of
+  //! <code>ClassHelper.createArray("java.lang.Object", 1)</code>,
+  //! invoking ::createArray(Object, int),
+  //! whereas <code>javaArray('java.lang.Object', 1, 1)</code>
+  //! this is translated into invocation of
+  //! <code>ClassHelper.createArray("java.lang.Object", 1, 1)</code>,
+  //! invoking ::createArray(Object, int[]).
   //!
   //! @param cls
   //!    the atomic component class given as a class object or as a string.
@@ -1265,25 +1202,26 @@
   //! @param dims
   //!    the dimensions which shall be non-negative but less than 256.
   //! @return
-  //!    an array with the given component type.
+  //!    an array with the given component type and dimensions.
   //!    If @c cls is a string, the class is loaded by #loader.
   //! @throws ClassNotFoundException
   //!    if @c cls is a string representing a class name
   //!    and if #loader could not find the according class.
-  // based on loader but only partially. 
+  //! @see ::createArray(Object, int)
+  // based on loader but only partially.
   // used by javaArray.m
   public static Object createArray (Object cls, int[] dims)
     throws ClassNotFoundException
   {
-    // FIXME: seems as if used in javaArray.m only.  
-    // Then more appropriate seems split into two methods: 
-    // one with cls is a Class other one with cls is a String 
-    // FIXME: if a class is given directly, 
-    // it is not guaranteed, that this is loaded via #loader 
-    // So this shall be fixed. 
-    // Typically, different usages are treated in m file invoking error 
-    // in the last else branch. 
-    // This would be appropriate here also. 
+    // FIXME: seems as if used in javaArray.m only.
+    // Then more appropriate seems split into two methods:
+    // one with cls is a Class other one with cls is a String
+    // FIXME: if a class is given directly,
+    // it is not guaranteed, that this is loaded via #loader
+    // So this shall be fixed.
+    // Typically, different usages are treated in m file invoking error
+    // in the last else branch.
+    // This would be appropriate here also.
     Class theClass;
     if (cls instanceof Class)
       {
@@ -1296,17 +1234,39 @@
       }
     else
       {
-        throw new IllegalArgumentException ("invalid class specification " +
-                                            cls);
+        throw new IllegalArgumentException ("invalid class specification "
+                                            + cls);
       }
 
     return Array.newInstance (theClass, dims);
   }
 
-
-  // public static Object createArray (Object cls, int length)
-  //   throws ClassNotFoundException
-  // {
-  //   return createArray (cls, new int[] {length});
-  // }
+  //! Return a one-dimensional array with entry type given by @c cls
+  //! with length by @c length.
+  //! The class may be given directly as a @ref Class object
+  //! or as a string via its name.
+  //! Used by @file javaArray.m defining @c javaArray only.
+  //!
+  //! @param cls
+  //!    the atomic component class given as a class object or as a string.
+  //!    If given as a string, the class is loaded via #loader.
+  //! @param length
+  //!    the length of the array to be created.
+  //! @return
+  //!    an array with the given component type and length.
+  //!    If @c cls is a string, the class is loaded by #loader.
+  //! @throws ClassNotFoundException
+  //!    if @c cls is a string representing a class name
+  //!    and if #loader could not find the according class.
+  //! @see ::createArray(Object, int)
+  // based on loader but only partially.
+  // used by javaArray.m
+  // would be superfluous with varargs introduced in java 1.5:
+  // the createArray (Object cls, int[] length)
+  // could be written createArray (Object cls, int... length)
+  public static Object createArray (Object cls, int length)
+    throws ClassNotFoundException
+  {
+    return createArray (cls, new int[] {length});
+  }
 }
