# HG changeset patch
# User Ernst Reissnere <rei3ner@arcor.de>
# Date 1468752592 -7200
#      Sun Jul 17 12:49:52 2016 +0200
# Node ID 432585a659ad1eeddd6ab93220206b662c6f461a
# Parent  748fb3d7733b0146b21a8daa242913eb9d54cd7c
- bugfix for 48013 adding method autoBoxNumber
- methods no_java-set now return void
- java.opts now allows comments and likewise do javaclasspath.txt and classpath.txt
- added a lot of docs.
- simplified code (hopefully) without changing functionality
- reformatting

diff -r 748fb3d7733b -r 432585a659ad libinterp/octave-value/ov-java.cc
--- a/libinterp/octave-value/ov-java.cc	Sun Jul 17 11:34:33 2016 +0200
+++ b/libinterp/octave-value/ov-java.cc	Sun Jul 17 12:49:52 2016 +0200
@@ -59,10 +59,9 @@
 
 #if defined (HAVE_JAVA)
 
-#define TO_JOBJECT(obj) reinterpret_cast<jobject> (obj)
-#define TO_JCLASS(obj) reinterpret_cast<jclass> (obj)
-
-#define TO_JNIENV(env) reinterpret_cast<JNIEnv *> (env)
+#define TO_JOBJECT(obj) reinterpret_cast<jobject>  (obj)
+#define TO_JCLASS(obj)  reinterpret_cast<jclass>   (obj)
+#define TO_JNIENV(env)  reinterpret_cast<JNIEnv *> (env)
 
 typedef jint (JNICALL *JNI_CreateJavaVM_t) (JavaVM **pvm, JNIEnv **penv,
                                             void *args);
@@ -119,14 +118,14 @@
   JNIEnv *env;
 };
 
-typedef java_local_ref<jobject> jobject_ref;
-typedef java_local_ref<jclass> jclass_ref;
-typedef java_local_ref<jstring> jstring_ref;
+typedef java_local_ref<jobject>           jobject_ref;
+typedef java_local_ref<jclass>             jclass_ref;
+typedef java_local_ref<jstring>           jstring_ref;
 typedef java_local_ref<jobjectArray> jobjectArray_ref;
-typedef java_local_ref<jintArray> jintArray_ref;
-typedef java_local_ref<jbyteArray> jbyteArray_ref;
+typedef java_local_ref<jintArray>       jintArray_ref;
+typedef java_local_ref<jbyteArray>     jbyteArray_ref;
 typedef java_local_ref<jdoubleArray> jdoubleArray_ref;
-typedef java_local_ref<jthrowable> jthrowable_ref;
+typedef java_local_ref<jthrowable>     jthrowable_ref;
 
 static std::string
 jstring_to_string (JNIEnv* jni_env, jstring s);
@@ -167,114 +166,198 @@
   Java_org_octave_Octave_needThreadedInvokation (JNIEnv *, jclass);
 }
 
+/**
+ * The list of current java virtual machines (JVMs) 
+ * provided by the Java Native Interface (JNI) 
+ * or 0 if no JVM is provided. 
+ */
 static JavaVM *jvm = 0;
+
 static bool jvm_attached = false;
 
-// Need to keep hold of the shared library handle until exit.
+// Need to keep hold of the shared library handle until exit. 
+// **** ER: Seems unneeded for __APPLE__ and __MACH__
 static octave::dynamic_library jvm_lib;
 
+// **** ER: Seeems unneeded. 
 static std::map<int,octave_value> listener_map;
+
+/**
+ * Maps an identifier onto the according <code>octave_value</code>. 
+ * This is used for boxing (i.e. in #box(JNIEnv*, void*, void*)) 
+ * of a reference: return the value of the according id 
+ * obtained from <code>org.octave.OctaveReference.getID()</code>. 
+ * For unboxing (i.e. in 
+ * #unbox(JNIEnv*, octave_value&, jobject_ref&, jclass_ref&)), 
+ * Used in #Java_org_octave_Octave_doInvoke 
+ * to invoke the according reference 
+ */
+// **** ER: set as a side effect by methods box and unbox
 static std::map<int,octave_value> octave_ref_map;
+
+/**
+ * The number of entries added to #octave_ref_map. 
+ * This is used to determine the identifier of the key-value pair. 
+ * Note that this is increased only. 
+ * It is not decreased if a reference is removed from #octave_ref_map. 
+ */
 static int octave_java_refcount = 0;
+
 static long octave_thread_ID = -1;
 
 bool Vjava_matrix_autoconversion = false;
 bool Vjava_unsigned_autoconversion = true;
 bool Vdebug_java = false;
 
+/**
+ * Represents the set of arguments passed to a java virtual machine. 
+ * The constructor creates the empty set of arguments 
+ * Method #read_java_opts reads options from a file, 
+ * #add is to add a single option. 
+ * Method #to_args is used to return the arguments 
+ * previously read or added 
+ * and to pass to #JNI_CreateJavaVM for creating a jvm. 
+ * Note that #to_args returns the options 
+ * read in since previous invocation of #to_args or since creation. 
+ */
 class JVMArgs
-{
-public:
-
-  JVMArgs (void)
   {
-    vm_args.version = JNI_VERSION_1_2;
-    vm_args.nOptions = 0;
-    vm_args.options = 0;
-    vm_args.ignoreUnrecognized = false;
-  }
-
-  ~JVMArgs (void)
-  {
-    clean ();
-  }
-
-  JavaVMInitArgs *to_args ()
-  {
-    update ();
-    return &vm_args;
-  }
-
-  void add (const std::string& opt)
-  {
-    java_opts.push_back (opt);
-  }
-
-  void read_java_opts (const std::string& filename)
-  {
-    std::ifstream js (filename.c_str ());
-
-    if (! js.bad () && ! js.fail ())
-      {
-        std::string line;
-
-        while (! js.eof () && ! js.fail ())
-          {
-            std::getline (js, line);
-
-            if (line.find ("-") == 0)
-              java_opts.push_back (line);
-            else if (line.length () > 0 && Vdebug_java)
-              std::cerr << "invalid JVM option, skipping: " << line << std::endl;
-          }
-      }
-  }
-
-private:
-
-  void clean (void)
-  {
-    if (vm_args.options != 0)
-      {
-        for (int i = 0; i < vm_args.nOptions; i++)
-          delete [] vm_args.options[i].optionString;
-
-        delete [] vm_args.options;
-
-        vm_args.options = 0;
-        vm_args.nOptions = 0;
-      }
-  }
-
-  void update (void)
-  {
-    clean ();
-
-    if (java_opts.size () > 0)
-      {
-        int index = 0;
-
-        vm_args.nOptions = java_opts.size ();
-        vm_args.options = new JavaVMOption [vm_args.nOptions];
-
-        for (std::list<std::string>::const_iterator it = java_opts.begin ();
-             it != java_opts.end (); ++it)
-          {
-            if (Vdebug_java)
-              std::cout << *it << std::endl;
-            vm_args.options[index++].optionString = strsave ((*it).c_str ());
-          }
-
-        java_opts.clear ();
-      }
-  }
-
-private:
-
-  JavaVMInitArgs vm_args;
-
-  std::list<std::string> java_opts;
-};
+  public:
+
+    /**
+     * Create empty option set for JNI version 1.2 and higher. 
+     */
+    JVMArgs (void)
+    {
+      vm_args.version = JNI_VERSION_1_2;
+      vm_args.nOptions = 0;
+      vm_args.options = 0;
+      vm_args.ignoreUnrecognized = false;
+    }
+
+    ~JVMArgs (void)
+    {
+      clean ();
+    }
+
+    /**
+     * Return the arguments for creating a jvm e.g. by #JNI_CreateJavaVM. 
+     *
+     * @return
+     *    the arguments read into this object 
+     *    via #read_java_opts and #add 
+     *    since creation or last invocation of this method. 
+     */
+    JavaVMInitArgs *to_args ()
+    {
+      update ();
+      return &vm_args;
+    }
+
+    /**
+     * Add the given option to #java_opts. 
+     */
+    void add (const std::string& opt)
+    {
+      java_opts.push_back (opt);
+    }
+
+    /**
+     * Read options for creation of a VM from filename 
+     * into #java_opts if possible. 
+     * Each line in the given file typically starts with <code>-</code> 
+     * and represents an option. 
+     * Empty lines and 
+     * lines starting with <code>#</code> or with <code>%</code> are ignored. 
+     * Other lines are ignored also except if debugging is on. 
+     *
+     * @param filename
+     *    the name of an options file. 
+     *    Each line represents an option. 
+     *    The line is ignored, if it does not start with '-'. 
+     */
+    void read_java_opts (const std::string& filename)
+    {
+      std::ifstream js (filename.c_str ());
+
+      if (! js.bad () && ! js.fail ())
+        {
+          std::string line;
+
+          while (! js.eof () && ! js.fail ())
+            {
+              std::getline (js, line);
+              if (line.length () == 0 || line[0] == '#' || line[0] == '%')
+                continue;// skip comments and empty lines 
+
+              if (line.find ("-") == 0)
+                java_opts.push_back (line);
+              else if (Vdebug_java)
+                std::cerr << "invalid JVM option, skipping: " << line << std::endl;
+            } // while 
+        }
+    }
+
+  private:
+
+    /**
+     * Clear the options in #vm_args by need: 
+     * If the options-field is 0, deletes each option and sets nOptions to 0. 
+     */
+    void clean (void)
+    {
+      if (vm_args.options != 0)
+        {
+          for (int i = 0; i < vm_args.nOptions; i++)
+            delete [] vm_args.options[i].optionString;
+
+          delete [] vm_args.options;
+
+          vm_args.options = 0;
+          vm_args.nOptions = 0;
+        }
+    }
+
+    /**
+     * Update the options in #vm_args 
+     * according to the options read into #java_opts 
+     * and clears #java_opts thereafter. 
+     *
+     * @see #read_java_opts
+     */
+    void update (void)
+    {
+      clean ();
+
+      if (java_opts.size () > 0)
+        {
+          int index = 0;
+
+          vm_args.nOptions = java_opts.size ();
+          vm_args.options = new JavaVMOption [vm_args.nOptions];
+
+          for (std::list<std::string>::const_iterator it = java_opts.begin ();
+               it != java_opts.end (); ++it)
+            {
+              if (Vdebug_java)
+                std::cout << *it << std::endl;
+              vm_args.options[index++].optionString = strsave ((*it).c_str ());
+            }
+
+          java_opts.clear ();
+        }
+    }
+
+  private:
+
+    // defined in jni.h
+    JavaVMInitArgs vm_args;
+
+    /**
+     * The list of java options as strings. 
+     */
+    std::list<std::string> java_opts;
+}; // class JVMArgs 
 
 #if defined (OCTAVE_USE_WINDOWS_API)
 
@@ -352,6 +435,25 @@
 
 #endif
 
+/**
+ * Return the initial java directory. 
+ * This is the system variable <code>OCTAVE_JAVA_DIR</code> if set; 
+ * otherwise <code>OCTAVE_FCNFILEDIR/java/</code>. 
+ * Typically, <code>OCTAVE_FCNFILEDIR</code> is where all scripts reside 
+ * and in <code>OCTAVE_FCNFILEDIR/java/</code> there are 
+ * <ul>
+ * <li>
+ * java-specific m-scripts like <code>javaclasspath.m</code> 
+ * <li>
+ * The java classes required by the java integration packaged in 
+ * <code>octave.jar</code> 
+ * <li>
+ * optionally the java options file <code>java.opts</code> 
+ * <li>
+ * optionally the java classpath files <code>javaclasspath.txt</code> or 
+ * (deprecated) <code>classpath.txt</code>. 
+ * </ul>
+ */
 static std::string
 initial_java_dir (void)
 {
@@ -368,17 +470,18 @@
   return java_dir;
 }
 
-// Read the content of a file filename (usually "classpath.txt")
-//
-// Returns a string with all lines concatenated and separated
-// by the path separator character.
-// The return string also starts with a path separator so that
-// it can be appended easily to a base classpath.
-//
-// The file "classpath.txt" must contain single lines, each
-// with a classpath.
-// Comment lines starting with a '#' or a '%' in column 1 are allowed.
-
+/**
+ * Read the content of a file filename 
+ * (usually <code>javaclasspath.txt</code> 
+ * but for backward compatibility also <code>classpath.txt</code>)
+ * <p>
+ * Empty lines and comment lines starting with a '#' or a '%' are allowed 
+ * and ignored. 
+ * All other lines are interpreted as entry of the static classpath. 
+ * <p>
+ * Returns a string with all non-ignored lines 
+ * preceeded with the path separator character and concatenated.
+ */
 static std::string
 read_classpath_txt (const std::string& filepath)
 {
@@ -394,30 +497,50 @@
         {
           std::getline (fs, line);
 
-          if (line.length () > 0)
-            {
-              if (line[0] == '#' || line[0] == '%')
-                ; // skip comments
-              else
-                {
-                  // prepend separator character
-                  classpath.append (octave::directory_path::path_sep_str ());
-
-                  // append content of line without whitespace
-                  int last = line.find_last_not_of (" \t\f\v\r\n");
-
-                  classpath.append (octave::sys::file_ops::tilde_expand (line.substr (0, last+1)));
-                }
-            }
-        }
-    }
-
-  return (classpath);
+          if (line.length () == 0 || line[0] == '#' || line[0] == '%')
+            continue;// skip comments and empty lines 
+
+          // prepend separator character
+          classpath.append (octave::directory_path::path_sep_str ());
+
+          // append content of line without whitespace
+          int last = line.find_last_not_of (" \t\f\v\r\n");
+
+          classpath.append (octave::sys::file_ops::tilde_expand (line.substr (0, last+1)));
+        } // while 
+    } // if 
+
+  return classpath;
 }
 
+/**
+ * Set up and return the initial (static) class path. 
+ * The first entry points simply to <code>octave.jar</code> 
+ * residing in #initial_java_dir(). 
+ * This is the directory where also the m-files for java are located 
+ * like <code>which javaclasspath.m</code> 
+ * which can be retrived by <code>which javaclasspath</code>. 
+ * <p>
+ * Then, append paths to the classpath read from files 
+ * <code>javaclasspath.txt</code> first and then <code>classpath.txt</code> 
+ * each searched for in the following ordering: 
+ * <ol>
+ * <li> in the current directory 
+ * <li> in the home directory of the user 
+ * <li> in #initial_java_dir(). 
+ * </ol>
+ * These files are read by #read_classpath_txt 
+ * the documentation of which offer further information on the format 
+ * each line represents an entry of the classpath. 
+ *
+ * @return
+ *    the initial (static) classpath. 
+ */
 static std::string
 initial_class_path (void)
 {
+  // java_dir is where octave.jar resides 
+  // and java-specific m-files like javaclasspath.m 
   std::string java_dir = initial_java_dir ();
 
   std::string retval = java_dir;
@@ -442,7 +565,7 @@
           // 2) User's home directory
           // 3) Octave installation directory where octave.jar resides
 
-          std::string cwd = octave::sys::env::get_current_directory ();
+          std::string cwd      = octave::sys::env::get_current_directory ();
           std::string home_dir = octave::sys::env::get_home_directory ();
 
           // The filename is "javaclasspath.txt", but historically
@@ -493,17 +616,22 @@
                       retval.append (classpath);
                     }
                 }
-            }
-        }
+            } // for 
+        } // if (jar_exists)
       else
         error ("octave.jar does not exist: %s", jar_file.c_str ());
-    }
+    } // if (! retval.empty ()) 
   else
     error ("initial java dir is empty");
 
   return retval;
 }
 
+/**
+ * Initialize the java virtual machine (jvm) 
+ * setting an environment, creating a virtual machine of none is present 
+ * and attaching to it. 
+ */
 static void
 initialize_jvm (void)
 {
@@ -661,10 +789,12 @@
       // No JVM exists, create one
 
       JVMArgs vm_args;
-
+      // sets up the static class path 
       vm_args.add ("-Djava.class.path=" + initial_class_path ());
-      vm_args.add ("-Xrs");
+      // sets up the class of the system class loader 
       vm_args.add ("-Djava.system.class.loader=org.octave.OctClassLoader");
+      vm_args.add ("-Xrs");// Reduces the use of os-signals by the JVM. 
+      // FIXME: In Matlab, there are more locations possible for java.opts
       vm_args.read_java_opts (initial_java_dir () + octave::sys::file_ops::dir_sep_str () +
                               "java.opts");
 
@@ -678,7 +808,8 @@
 
 #else
 
-      if (JNI_CreateJavaVM (&jvm, reinterpret_cast<void **> (&current_env),
+      if (JNI_CreateJavaVM (&jvm, 
+                            reinterpret_cast<void **> (&current_env),
                             vm_args.to_args ()) != JNI_OK)
         error ("unable to start Java VM in %s", jvm_lib_path.c_str ());
 
@@ -687,8 +818,11 @@
 #endif
 
   setlocale (LC_ALL, locale.c_str ());
-}
-
+} // initialize_jvm
+
+/**
+ * Terminate, i.e. detach ****
+ */
 static void
 terminate_jvm (void)
 {
@@ -743,6 +877,9 @@
   return retval;
 }
 
+/**
+ * Return the JNI-environment of the current JVM #jvm. 
+ */
 static inline JNIEnv *
 thread_jni_env (void)
 {
@@ -781,6 +918,12 @@
 #endif
 }
 
+/**
+ * Return whether #java_object is an instance of <code>cls_name</code>. 
+ *
+ * @param cls_name
+ *    The fully qualified classname with separator <code>.</code>. 
+ */
 bool
 octave_java::is_instance_of (const std::string& cls_name) const
 {
@@ -862,9 +1005,12 @@
             {
               jclass_ref syscls (jni_env,
                                  jni_env->FindClass ("java/lang/System"));
-              jmethodID mID = jni_env->GetStaticMethodID (syscls, "getProperty", "(Ljava/lang/String;)Ljava/lang/String;");
+              jmethodID mID = jni_env->GetStaticMethodID (syscls, 
+                                                          "getProperty", 
+                                                          "(Ljava/lang/String;)Ljava/lang/String;");
               jstring_ref js (jni_env, jni_env->NewStringUTF ("octave.class.loader"));
-              js = reinterpret_cast<jstring> (jni_env->CallStaticObjectMethod (syscls, mID, jstring (js)));
+              js = reinterpret_cast<jstring> (jni_env->CallStaticObjectMethod 
+                                              (syscls, mID, jstring (js)));
               class_loader = jstring_to_string (jni_env, jstring (js));
               std::replace (class_loader.begin (), class_loader.end (),
                             '.', '/');
@@ -967,56 +1113,71 @@
   return retval;
 }
 
+/**
+ * Wraps <code>org.octave.ClassHelper.arraySubsref(Object, int[][])</code>. 
+ */
+//  required by subsref
 static octave_value
-get_array_elements (JNIEnv *jni_env, jobject jobj,
+get_array_elements (JNIEnv *jni_env, 
+                    jobject jobj,
                     const octave_value_list& idx)
 {
   octave_value retval;
   jobject_ref resObj (jni_env);
   jobject_ref java_idx (jni_env, make_java_index (jni_env, idx));
 
-  jclass_ref helperClass (jni_env, find_octave_class (jni_env, "org/octave/ClassHelper"));
-  jmethodID mID = jni_env->GetStaticMethodID (helperClass, "arraySubsref", "(Ljava/lang/Object;[[I)Ljava/lang/Object;");
-  resObj = jni_env->CallStaticObjectMethod (helperClass, mID, jobj, jobject (java_idx));
-
-  if (resObj)
-    retval = box (jni_env, resObj);
-  else
-    retval = check_exception (jni_env);
+  jclass_ref helperClass (jni_env, 
+                          find_octave_class (jni_env, 
+                                             "org/octave/ClassHelper"));
+  jmethodID mID = jni_env
+    ->GetStaticMethodID (helperClass, 
+                         "arraySubsref", 
+                         // parameter types 
+                          "(Ljava/lang/Object;[[I)Ljava/lang/Object;");
+  resObj = jni_env->CallStaticObjectMethod 
+    (helperClass, mID, jobj, jobject (java_idx));
+
+  retval = resObj
+    ? box (jni_env, resObj)
+    : check_exception (jni_env);
 
   octave_set_default_fpucw ();
 
   return retval;
 }
 
-static octave_value
-set_array_elements (JNIEnv *jni_env, jobject jobj,
-                    const octave_value_list& idx, const octave_value& rhs)
+/**
+ * Wraps 
+ * <code>org.octave.ClassHelper.arraySubsasgn(Object, int[][], Object)</code>. 
+ */
+// used by subsasgn
+static void
+set_array_elements (JNIEnv *jni_env, 
+                    jobject jobj,
+                    const octave_value_list& idx, 
+                    const octave_value& rhs)
 {
-  octave_value retval;
-
-  jclass_ref rhsCls (jni_env);
+  jclass_ref  rhsCls (jni_env);
   jobject_ref resObj (jni_env);
   jobject_ref rhsObj (jni_env);
   jobject_ref java_idx (jni_env, make_java_index (jni_env, idx));
 
   if (unbox (jni_env, rhs, rhsObj, rhsCls))
     {
-      jclass_ref helperClass (jni_env, find_octave_class (jni_env, "org/octave/ClassHelper"));
-      jmethodID mID = jni_env->GetStaticMethodID (helperClass, "arraySubsasgn",
-          "(Ljava/lang/Object;[[ILjava/lang/Object;)Ljava/lang/Object;");
-      resObj = jni_env->CallStaticObjectMethod (helperClass, mID,
-          jobj, jobject (java_idx), jobject (rhsObj));
+      jclass_ref helperClass (jni_env, 
+                              find_octave_class (jni_env, 
+                                                 "org/octave/ClassHelper"));
+      jmethodID mID = jni_env
+        ->GetStaticMethodID (helperClass, 
+                             "arraySubsasgn",
+                             // parameter types 
+                             "(Ljava/lang/Object;[[ILjava/lang/Object;)" 
+                             "Ljava/lang/Object;");
+      jni_env->CallStaticObjectMethod 
+        (helperClass, mID, jobj, jobject (java_idx), jobject (rhsObj));
     }
 
-  if (resObj)
-    retval = box (jni_env, resObj);
-  else
-    retval = check_exception (jni_env);
-
   octave_set_default_fpucw ();
-
-  return retval;
 }
 
 static string_vector
@@ -1028,30 +1189,41 @@
 
   if (jni_env)
     {
-      jclass_ref cls (jni_env, jni_env->GetObjectClass (jobj));
+      jclass_ref  cls (jni_env, jni_env->GetObjectClass (jobj));
       jclass_ref ccls (jni_env, jni_env->GetObjectClass (cls));
-      jmethodID getMethods_ID = jni_env->GetMethodID (ccls, "getMethods", "()[Ljava/lang/reflect/Method;");
-      jmethodID getFields_ID = jni_env->GetMethodID (ccls, "getFields", "()[Ljava/lang/reflect/Field;");
-      jobjectArray_ref mList (jni_env, reinterpret_cast<jobjectArray> (jni_env->CallObjectMethod (cls, getMethods_ID)));
-      jobjectArray_ref fList (jni_env, reinterpret_cast<jobjectArray> (jni_env->CallObjectMethod (cls, getFields_ID)));
+      jmethodID getMethods_ID = jni_env->GetMethodID 
+        (ccls, "getMethods", "()[Ljava/lang/reflect/Method;");
+      jmethodID getFields_ID  = jni_env->GetMethodID 
+        (ccls, "getFields", "()[Ljava/lang/reflect/Field;");
+      jobjectArray_ref mList (jni_env, reinterpret_cast<jobjectArray> 
+                              (jni_env->CallObjectMethod (cls, getMethods_ID)));
+      jobjectArray_ref fList (jni_env, reinterpret_cast<jobjectArray> 
+                              (jni_env->CallObjectMethod (cls, getFields_ID)));
       int mLen = jni_env->GetArrayLength (mList);
       int fLen = jni_env->GetArrayLength (fList);
-      jclass_ref mCls (jni_env, jni_env->FindClass ("java/lang/reflect/Method"));
-      jclass_ref fCls (jni_env, jni_env->FindClass ("java/lang/reflect/Field"));
-      jmethodID m_getName_ID = jni_env->GetMethodID (mCls, "getName", "()Ljava/lang/String;");
-      jmethodID f_getName_ID = jni_env->GetMethodID (fCls, "getName", "()Ljava/lang/String;");
+      jclass_ref mCls (jni_env, jni_env->FindClass("java/lang/reflect/Method"));
+      jclass_ref fCls (jni_env, jni_env->FindClass("java/lang/reflect/Field"));
+      jmethodID m_getName_ID = jni_env->GetMethodID (mCls, 
+                                                     "getName", 
+                                                     "()Ljava/lang/String;");
+      jmethodID f_getName_ID = jni_env->GetMethodID (fCls, 
+                                                     "getName", 
+                                                     "()Ljava/lang/String;");
 
       for (int i = 0; i < mLen; i++)
         {
           jobject_ref meth (jni_env, jni_env->GetObjectArrayElement (mList, i));
-          jstring_ref methName (jni_env, reinterpret_cast<jstring> (jni_env->CallObjectMethod (meth, m_getName_ID)));
+          jstring_ref methName(jni_env, reinterpret_cast<jstring> 
+                               (jni_env->CallObjectMethod(meth, m_getName_ID)));
           name_list.push_back (jstring_to_string (jni_env, methName));
         }
 
       for (int i = 0; i < fLen; i++)
         {
-          jobject_ref field (jni_env, jni_env->GetObjectArrayElement (fList, i));
-          jstring_ref fieldName (jni_env, reinterpret_cast<jstring> (jni_env->CallObjectMethod (field, f_getName_ID)));
+          jobject_ref field (jni_env, jni_env->GetObjectArrayElement(fList, i));
+          jstring_ref fieldName (jni_env, reinterpret_cast<jstring> 
+                                 (jni_env->CallObjectMethod 
+                                  (field, f_getName_ID)));
           name_list.push_back (jstring_to_string (jni_env, fieldName));
         }
 
@@ -1119,13 +1291,108 @@
 
 #define TO_JAVA(obj) dynamic_cast<octave_java*> ((obj).internal_rep ())
 
+
+/**
+ * Return whether jobj is an instance of a wrapper class of a numeric class. 
+ * These classes are the integer classes <code>Byte</code>, 
+ * <code>Integer</code>, <code>Long</code> and <code>Short</code>, 
+ * and the floating point classes <code>Double</code> and <code>Float</code>. 
+ * All these classes implement <code>java.lang.Number</code> 
+ * and thus <code>Number.doubleValue()</code>. 
+ * This is the method applied for autoboxing. 
+ *
+ * @param jobj
+ *    an object 
+ * @return
+ *    whether <code>jobj</code>, 
+ */
+static bool autoBoxNumber(JNIEnv *jni_env, jobject jobj) {
+  jclass_ref cls (jni_env);
+  cls = jni_env->FindClass ("java/lang/Number");
+  if (!jni_env->IsInstanceOf (jobj, cls)) 
+    return false;
+
+  cls = jni_env->FindClass ("java/lang/Byte");
+  if (jni_env->IsInstanceOf (jobj, cls)) 
+    return true;
+  cls = jni_env->FindClass ("java/lang/Double");
+  if (jni_env->IsInstanceOf (jobj, cls)) 
+    return true;
+  cls = jni_env->FindClass ("java/lang/Float");
+  if (jni_env->IsInstanceOf (jobj, cls)) 
+    return true;
+  cls = jni_env->FindClass ("java/lang/Integer");
+  if (jni_env->IsInstanceOf (jobj, cls)) 
+    return true;
+  cls = jni_env->FindClass ("java/lang/Long");
+  if (jni_env->IsInstanceOf (jobj, cls)) 
+    return true;
+  cls = jni_env->FindClass ("java/lang/Short");
+  if (jni_env->IsInstanceOf (jobj, cls)) 
+    return true;
+
+  return false;
+}
+
+/**
+ * Perform boxing, 
+ * i.e. convert java-type object <code>jobj_arg</code> 
+ * with class <code>jcls_arg</code> to a octave-type object 
+ * and return it. 
+ *
+ * @param[in] jni_env
+ *    
+ * @param[in] jobj_arg
+ *    a java-object 
+ * @param[in] jcls_arg
+ *    the class of the according object. 
+ * @return
+ *    <ul>
+ *    <li>
+ *    if <code>jobj_arg</code> is of type 
+ *    <code>Byte</code>, <code>Short</code>, <code>Integer</code>, 
+ *    <code>Long</code>, <code>Float</code>, <code>Double</code>, 
+ *    all implementing <code>java.lang.Number<code>, 
+ *    it is converted to double via method <code>Number.doubleValue()<code>, 
+ *    <li>
+ *    if <code>jobj_arg</code> is of type <code>Boolean</code>, 
+ *    it is converted to bool via method <code>Boolean.booleanValue()<code>, 
+ *    <li>
+ *    if <code>jobj_arg</code> is of type <code>String</code>, 
+ *    it is converted to a <code>jstring</code>, 
+ *    via method #jstring_to_string (JNIEnv*, jstring), 
+ *    <li>
+ *    if <code>jobj_arg</code> is of type <code>Character</code>, 
+ *    it is converted to a <code>char</code> 
+ *    via method <code>Number.charValue()<code> 
+ *    and then into a string via octave_value::convert_to_str(bool, bool), 
+ *    <li>
+ *    if <code>jobj_arg</code> is a one-dimensional array 
+ *    with primitive entry type or its wrapper as <code>int[]</code>, 
+ *    then conversion is performed according to a certain table 
+ *    which shall be documented. ****
+ *    <li>
+ *    if <code>jobj_arg</code> is a matrix and autoconversion is on 
+ *    according to #Vjava_matrix_autoconversion, 
+ *    another algorithm is used. **** 
+ *    <li>
+ *    if <code>jobj_arg</code> is an octave reference, 
+ *    i.e. an instance of <code>org.octave.OctaveReference</code>, 
+ *    the according octave-object is taken from #octave_ref_map. 
+ *    <li>
+ *    in all other cases, there is no autoconversion: 
+ *    instead, an instanceo of octave_java is created 
+ *    wrapping the java-object. 
+ *    </ul>
+ *    a matrix if <code>jobj_arg</code> 
+ */
 static octave_value
 box (JNIEnv *jni_env, void *jobj_arg, void *jcls_arg)
 {
   octave_value retval;
 
   jobject jobj = TO_JOBJECT (jobj_arg);
-  jclass jcls = TO_JCLASS (jcls_arg);
+  jclass  jcls = TO_JCLASS  (jcls_arg);
 
   jclass_ref cls (jni_env);
 
@@ -1134,10 +1401,10 @@
 
   while (retval.is_undefined ())
     {
-      // Convert a scalar of any numeric class (byte, short, integer, long,
-      // float, double) to a double value.  Matlab does the same thing.
+      // Convert a scalar of any numeric class wrapping a primitive class 
+      // (byte, short, integer, long, float, double) to a double value.  
       cls = jni_env->FindClass ("java/lang/Number");
-      if (jni_env->IsInstanceOf (jobj, cls))
+      if (autoBoxNumber(jni_env, jobj))
         {
           jmethodID m = jni_env->GetMethodID (cls, "doubleValue", "()D");
           retval = jni_env->CallDoubleMethod (jobj, m);
@@ -1181,14 +1448,15 @@
           break; \
         }
 
-      BOX_PRIMITIVE_ARRAY (jdouble,  "[D", Double,  )
-      BOX_PRIMITIVE_ARRAY (jboolean, "[Z", Boolean, bool)
-      BOX_PRIMITIVE_ARRAY (jfloat,   "[F", Float,   Float)
-      BOX_PRIMITIVE_ARRAY (jchar,    "[C", Char,    char)
-      BOX_PRIMITIVE_ARRAY (jbyte,    "[B", Byte,    int8)
-      BOX_PRIMITIVE_ARRAY (jshort,   "[S", Short,   int16)
-      BOX_PRIMITIVE_ARRAY (jint,     "[I", Int,     int32)
-      BOX_PRIMITIVE_ARRAY (jlong,    "[J", Long,    int64)
+      //                   J._TYPE,  J._ID, J._TYPE_CAP, OCTAVE_ID
+      BOX_PRIMITIVE_ARRAY (jdouble,  "[D",  Double,            )
+      BOX_PRIMITIVE_ARRAY (jboolean, "[Z",  Boolean,      bool )
+      BOX_PRIMITIVE_ARRAY (jfloat,   "[F",  Float,        Float)
+      BOX_PRIMITIVE_ARRAY (jchar,    "[C",  Char,         char )
+      BOX_PRIMITIVE_ARRAY (jbyte,    "[B",  Byte,         int8 )
+      BOX_PRIMITIVE_ARRAY (jshort,   "[S",  Short,        int16)
+      BOX_PRIMITIVE_ARRAY (jint,     "[I",  Int,          int32)
+      BOX_PRIMITIVE_ARRAY (jlong,    "[J",  Long,         int64)
 
 #undef BOX_PRIMITIVE_ARRAY
 
@@ -1199,7 +1467,8 @@
           if (jni_env->IsInstanceOf (jobj, cls))
             {
               jmethodID mID = jni_env->GetMethodID (cls, "getDims", "()[I");
-              jintArray_ref iv (jni_env, reinterpret_cast<jintArray> (jni_env->CallObjectMethod (jobj, mID)));
+              jintArray_ref iv (jni_env, reinterpret_cast<jintArray> 
+                                (jni_env->CallObjectMethod (jobj, mID)));
               jint *iv_data = jni_env->GetIntArrayElements (jintArray (iv), 0);
               dim_vector dims;
               dims.resize (jni_env->GetArrayLength (jintArray (iv)));
@@ -1208,8 +1477,12 @@
                 dims(i) = iv_data[i];
 
               jni_env->ReleaseIntArrayElements (jintArray (iv), iv_data, 0);
-              mID = jni_env->GetMethodID (cls, "getClassName", "()Ljava/lang/String;");
-              jstring_ref js (jni_env, reinterpret_cast<jstring> (jni_env->CallObjectMethod (jobj, mID)));
+              mID = jni_env->GetMethodID (cls, 
+                                          "getClassName", 
+                                          "()Ljava/lang/String;");
+              jstring_ref js (jni_env, 
+                              reinterpret_cast<jstring> 
+                              (jni_env->CallObjectMethod (jobj, mID)));
 
               std::string s = jstring_to_string (jni_env, js);
 
@@ -1217,8 +1490,12 @@
                 {
                   NDArray m (dims);
                   mID = jni_env->GetMethodID (cls, "toDouble", "()[D");
-                  jdoubleArray_ref dv (jni_env, reinterpret_cast<jdoubleArray> (jni_env->CallObjectMethod (jobj, mID)));
-                  jni_env->GetDoubleArrayRegion (dv, 0, m.numel (), m.fortran_vec ());
+                  jdoubleArray_ref dv (jni_env, reinterpret_cast<jdoubleArray> 
+                                       (jni_env->CallObjectMethod (jobj, mID)));
+                  jni_env->GetDoubleArrayRegion (dv, 
+                                                 0, 
+                                                 m.numel (), 
+                                                 m.fortran_vec ());
                   retval = m;
                   break;
                 }
@@ -1265,7 +1542,7 @@
                     }
                 }
             }
-        }
+        } // if(Vjava_matrix_autoconversion)
 
       cls = find_octave_class (jni_env, "org/octave/OctaveReference");
       if (jni_env->IsInstanceOf (jobj, cls))
@@ -1274,6 +1551,7 @@
           int ID = jni_env->CallIntMethod (jobj, mID);
           std::map<int,octave_value>::iterator it = octave_ref_map.find (ID);
 
+          // FIXME: what if the end?? 
           if (it != octave_ref_map.end ())
             retval = it->second;
 
@@ -1283,16 +1561,16 @@
       // No suitable class found.  Return a generic octave_java object
       retval = octave_value (new octave_java (jobj, jcls));
       break;
-    }
+    } // while 
 
   return retval;
-}
+} // box 
 
 static octave_value
 box_more (JNIEnv *jni_env, void *jobj_arg, void *jcls_arg)
 {
   jobject jobj = TO_JOBJECT (jobj_arg);
-  jclass jcls = TO_JCLASS (jcls_arg);
+  jclass  jcls = TO_JCLASS  (jcls_arg);
 
   octave_value retval = box (jni_env, jobj, jcls);
 
@@ -1385,8 +1663,71 @@
   return retval;
 }
 
+/**
+ * Perform unboxing, 
+ * i.e. convert octave-type value <code>val</code>
+ * to java-type object <code>jobj</code> with java-class <code>jcls</code>: 
+ *
+ * <ul>
+ * <li>
+ * If <code>val</code> is a java-object, 
+ * <code>jobj</code> is <code>val</code> casted accordingly 
+ * and <code>jcls</code> is its (java-)class. 
+ * As a side effect, <code>jobj</code> is detached. 
+ * <li>
+ * If <code>val</code> is a string-object, 
+ * <code>jobj</code> is <code>val</code> converted into an UTF-string 
+ * and <code>jcls</code> is its class. 
+ * <li>
+ * If <code>val</code> is a cellstring-object 
+ * (a cell array of character vectors), 
+ * <code>jobj</code> is <code>val</code> converted into an array of UTF-strings 
+ * and <code>jcls</code> is its class. 
+ * <li>
+ * If <code>val</code> is a primitive scalar, 
+ * i.e. an octave double, bool, float, conversion is done 
+ * according to a certain conversion table ****. 
+ * <li>
+ * If <code>val</code> is a matrix 
+ * and autoconverion is on according to #Vjava_matrix_autoconversion, 
+ * conversion is done using an appropriate constructor 
+ * in <code>org.octave.Matrix</code>. 
+ * <li>
+ * Else, for <code>val</code> a <code>org.octave.OctaveReference</code> 
+ * wrapping <code>val</code> is created. 
+ * This means that no real conversion is performed. 
+ * </ul>
+ *
+ * In general, if <code>val</code> is of type 
+ * int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t or uint64_t, 
+ * then <code>jobj</code>, the result of the conversion, 
+ * has is a wrapper of the according primitive java-type: 
+ * bool to Boolean, float to Float, double to Double 
+ * and for the integer types the least type allowing lossless conversion 
+ * ignoring sign. 
+ * Note that <code>jcls</code> is the according primitive java-class, 
+ * not the wrapper. 
+ * </ul>
+ *
+ * @param[in] jni_env
+ *    
+ * @param[in] val
+ *    an octave-value 
+ * @param[out] jobj
+ *    the java-object corresponding with <code>val</code>. 
+ * @param[out] jcls
+ *    the class of the according object <code>jobj</code>. 
+ * @return
+ *   whether unboxing succeeded. 
+ *   No success means that we have a matrix, autoconversion on, 
+ *   but the type of the matrix cannot be converted to a java-matrix, 
+ *   because there is no according constructor 
+ *   in <code>org.octave.Matrix</code>. 
+ */
 static bool
-unbox (JNIEnv *jni_env, const octave_value& val, jobject_ref& jobj,
+unbox (JNIEnv *jni_env, 
+       const octave_value& val, 
+       jobject_ref& jobj, 
        jclass_ref& jcls)
 {
   bool found = true;
@@ -1400,6 +1741,8 @@
     }
   else if (val.is_string ())
     {
+      // FIXME: Autoconversion of java Strings 
+      // seems not Matlab-conform to me (ER) 
       std::string s = val.string_value ();
 
       jobj = jni_env->NewStringUTF (s.c_str ());
@@ -1442,28 +1785,29 @@
       // Note that we do NOT handle char here because they are unboxed
       // into a String[], not into a char array
 
+      // UNBOX_PRIMITIVE_ARRAY(METHOD_T, OCTAVE_T, JAVA_T, JAVA_T_CAP)
       if (val.is_double_type ())
-        UNBOX_PRIMITIVE_ARRAY ( , , jdouble,  Double);
+        UNBOX_PRIMITIVE_ARRAY        (     ,      ,   jdouble,  Double);
       else if (val.is_bool_type ())
-        UNBOX_PRIMITIVE_ARRAY (bool_, bool, jboolean, Boolean);
+        UNBOX_PRIMITIVE_ARRAY        (bool_,   bool,  jboolean, Boolean);
       else if (val.is_float_type ())
-        UNBOX_PRIMITIVE_ARRAY (float_, Float, jfloat, Float);
+        UNBOX_PRIMITIVE_ARRAY       (float_,  Float,  jfloat,   Float);
       else if (val.is_int8_type ())
-        UNBOX_PRIMITIVE_ARRAY (int8_, int8, jbyte, Byte);
+        UNBOX_PRIMITIVE_ARRAY       (int8_,   int8,   jbyte,    Byte);
       else if (val.is_uint8_type ())
-        UNBOX_PRIMITIVE_ARRAY (uint8_, uint8, jbyte, Byte);
+        UNBOX_PRIMITIVE_ARRAY       (uint8_,  uint8,  jbyte,    Byte);
       else if (val.is_int16_type ())
-        UNBOX_PRIMITIVE_ARRAY (int16_, int16, jshort, Short);
+        UNBOX_PRIMITIVE_ARRAY       (int16_,  int16,  jshort,   Short);
       else if (val.is_uint16_type ())
-        UNBOX_PRIMITIVE_ARRAY (uint16_, uint16, jshort, Short);
+        UNBOX_PRIMITIVE_ARRAY       (uint16_, uint16, jshort,   Short);
       else if (val.is_int32_type ())
-        UNBOX_PRIMITIVE_ARRAY (int32_, int32, jint, Int);
+        UNBOX_PRIMITIVE_ARRAY       (int32_,  int32,  jint,     Int);
       else if (val.is_uint32_type ())
-        UNBOX_PRIMITIVE_ARRAY (uint32_, uint32, jint, Int);
+        UNBOX_PRIMITIVE_ARRAY       (uint32_, uint32, jint,     Int);
       else if (val.is_int64_type ())
-        UNBOX_PRIMITIVE_ARRAY (int64_, int64, jlong, Long);
+        UNBOX_PRIMITIVE_ARRAY       (int64_,  int64,  jlong,    Long);
       else if (val.is_uint64_type ())
-        UNBOX_PRIMITIVE_ARRAY (uint64_, uint64, jlong, Long);
+        UNBOX_PRIMITIVE_ARRAY       (uint64_, uint64, jlong,    Long);
 
 #undef UNBOX_PRIMITIVE_ARRAY
     }
@@ -1483,29 +1827,29 @@
       jobj = jni_env->NewObject (dcls, mid, ov); \
      } \
    while (0)
-
+      //UNBOX_PRIMITIVE_SCALAR (OCTAVE_T, METHOD_T,      JAVA_T,              JAVA_CON)
       if (val.is_double_type ())
-        UNBOX_PRIMITIVE_SCALAR (double, double, "java/lang/Double", "(D)V");
+        UNBOX_PRIMITIVE_SCALAR (double,   double,        "java/lang/Double",  "(D)V");
       else if (val.is_bool_type ())
-        UNBOX_PRIMITIVE_SCALAR (bool, bool, "java/lang/Boolean", "(Z)V");
+        UNBOX_PRIMITIVE_SCALAR (bool,     bool,          "java/lang/Boolean", "(Z)V");
       else if (val.is_float_type ())
-        UNBOX_PRIMITIVE_SCALAR (float, float, "java/lang/Float", "(F)V");
+        UNBOX_PRIMITIVE_SCALAR (float,    float,         "java/lang/Float",   "(F)V");
       else if (val.is_int8_type ())
-        UNBOX_PRIMITIVE_SCALAR (int8_t, int8_scalar, "java/lang/Byte", "(B)V");
+        UNBOX_PRIMITIVE_SCALAR (int8_t,   int8_scalar,   "java/lang/Byte",    "(B)V");
       else if (val.is_uint8_type ())
-        UNBOX_PRIMITIVE_SCALAR (uint8_t, uint8_scalar, "java/lang/Byte", "(B)V");
+        UNBOX_PRIMITIVE_SCALAR (uint8_t,  uint8_scalar,  "java/lang/Byte",    "(B)V");
       else if (val.is_int16_type ())
-        UNBOX_PRIMITIVE_SCALAR (int16_t, int16_scalar, "java/lang/Short", "(S)V");
+        UNBOX_PRIMITIVE_SCALAR (int16_t,  int16_scalar,  "java/lang/Short",   "(S)V");
       else if (val.is_uint16_type ())
-        UNBOX_PRIMITIVE_SCALAR (uint16_t, uint16_scalar, "java/lang/Short", "(S)V");
+        UNBOX_PRIMITIVE_SCALAR (uint16_t, uint16_scalar, "java/lang/Short",   "(S)V");
       else if (val.is_int32_type ())
-        UNBOX_PRIMITIVE_SCALAR (int32_t, int32_scalar, "java/lang/Integer", "(I)V");
+        UNBOX_PRIMITIVE_SCALAR (int32_t,  int32_scalar,  "java/lang/Integer", "(I)V");
       else if (val.is_uint32_type ())
         UNBOX_PRIMITIVE_SCALAR (uint32_t, uint32_scalar, "java/lang/Integer", "(I)V");
       else if (val.is_int64_type ())
-        UNBOX_PRIMITIVE_SCALAR (int64_t, int64_scalar, "java/lang/Long", "(J)V");
+        UNBOX_PRIMITIVE_SCALAR (int64_t, int64_scalar,   "java/lang/Long",    "(J)V");
       else if (val.is_uint64_type ())
-        UNBOX_PRIMITIVE_SCALAR (uint64_t, uint64_scalar, "java/lang/Long", "(J)V");
+        UNBOX_PRIMITIVE_SCALAR (uint64_t, uint64_scalar, "java/lang/Long",    "(J)V");
 
 #undef UNBOX_PRIMITIVE_SCALAR
       }
@@ -1527,9 +1871,10 @@
       jcls = jni_env->GetObjectClass (jobj);
     }
   else if (Vjava_matrix_autoconversion
-           && (val.is_matrix_type () || val.is_range ()) && val.is_real_type ())
+           && (val.is_matrix_type () || val.is_range ()) 
+           && val.is_real_type ())
     {
-      jclass_ref mcls (jni_env, find_octave_class (jni_env, "org/octave/Matrix"));
+      jclass_ref mcls(jni_env, find_octave_class(jni_env, "org/octave/Matrix"));
       dim_vector dims = val.dims ();
       jintArray_ref iv (jni_env, jni_env->NewIntArray (dims.ndims ()));
       jint *iv_data = jni_env->GetIntArrayElements (jintArray (iv), 0);
@@ -1598,8 +1943,19 @@
     }
 
   return found;
-}
-
+} // unbox 
+
+/**
+ * Convert a value list <code>args</code> 
+ * into a corresponding jobject list <code>jobjs</code> 
+ * and <code>jclss</code> are its corresponding (java-)classes. 
+ * This is done by applying 
+ * #unbox(JNIEnv*, octave_value&, jobject_ref&, jclass_ref&) 
+ * componentwise. 
+ *
+ * @return
+ *   whether unboxing succeeded. 
+ */
 static bool
 unbox (JNIEnv *jni_env, const octave_value_list& args,
        jobjectArray_ref& jobjs, jobjectArray_ref& jclss)
@@ -1618,7 +1974,7 @@
   for (int i = 0; i < args.length (); i++)
     {
       jobject_ref jobj (jni_env);
-      jclass_ref jcls (jni_env);
+      jclass_ref  jcls (jni_env);
 
       found = unbox (jni_env, args(i), jobj, jcls);
       if (! found)
@@ -1629,7 +1985,7 @@
     }
 
   return found;
-}
+} // unbox 
 
 static long
 get_current_thread_ID (JNIEnv *jni_env)
@@ -1637,7 +1993,9 @@
   if (jni_env)
     {
       jclass_ref cls (jni_env, jni_env->FindClass ("java/lang/Thread"));
-      jmethodID mID = jni_env->GetStaticMethodID (cls, "currentThread", "()Ljava/lang/Thread;");
+      jmethodID mID = jni_env->GetStaticMethodID (cls, 
+                                                  "currentThread", 
+                                                  "()Ljava/lang/Thread;");
       jobject_ref jthread (jni_env, jni_env->CallStaticObjectMethod (cls, mID));
 
       if (jthread)
@@ -1660,8 +2018,11 @@
 
   if (current_env)
     {
-      jclass_ref cls (current_env, find_octave_class (current_env, "org/octave/Octave"));
-      jmethodID mID = current_env->GetStaticMethodID (cls, "checkPendingAction", "()V");
+      jclass_ref cls (current_env, find_octave_class (current_env, 
+                                                      "org/octave/Octave"));
+      jmethodID mID = current_env->GetStaticMethodID (cls, 
+                                                      "checkPendingAction", 
+                                                      "()V");
       current_env->CallStaticVoidMethod (cls, mID);
 
       octave_set_default_fpucw ();
@@ -1695,14 +2056,39 @@
     }
 }
 
+/**
+ * Wrap 'argout = feval(funcName, argin, argout.length)' 
+ * decorated with some boxing/unboxing. 
+ * <p>
+ * This method defines 
+ * the call to 
+ * native org.octave.Octave#call(String, Object[], Object[]). 
+ * defined in scripts/org/octave/Octave.java. 
+ *
+ * @param env
+ *    
+ * @param 
+ *    
+ * @param funcName
+ *    the name of the function to be called. 
+ * @param argin
+ *    the array of input arguments. 
+ * @param argout
+ *    the array of output/return arguments.
+ * @return
+ *    whether unboxing of output succeeded. 
+ */
 JNIEXPORT jboolean JNICALL
-Java_org_octave_Octave_call (JNIEnv *env, jclass, jstring funcName,
-                             jobjectArray argin, jobjectArray argout)
+Java_org_octave_Octave_call (JNIEnv *env, 
+                             jclass, // unneeded? 
+                             jstring funcName,
+                             jobjectArray argin, 
+                             jobjectArray argout)
 {
   std::string fname = jstring_to_string (env, funcName);
 
   int nargout = env->GetArrayLength (argout);
-  int nargin = env->GetArrayLength (argin);
+  int nargin  = env->GetArrayLength (argin);
 
   octave_value_list varargin, varargout;
 
@@ -1714,16 +2100,42 @@
   jobjectArray_ref out_objs (env, argout), out_clss (env);
   out_objs.detach ();
   return unbox (env, varargout, out_objs, out_clss);
-}
-
+} // Java_org_octave_Octave_call 
+
+/**
+ * Remove the given identifyer from #octave_ref_map. 
+ * <p>
+ * This method defines 
+ * the call to 
+ * native org.octave.OctaveReference#doFinalize(int). 
+ * defined in scripts/org/octave/OctaveReferenc.java. 
+ */
 JNIEXPORT void JNICALL
 Java_org_octave_OctaveReference_doFinalize (JNIEnv *, jclass, jint ID)
 {
   octave_ref_map.erase (ID);
 }
 
+/**
+ * Wrap <code>feval(fct, ...)</code>, where fct is given by <code>ID</code>
+ * <p>
+ * This method defines 
+ * the call to 
+ * native org.octave.Octave#doInvoke(int, Object[]). 
+ * defined in scripts/org/octave/Octave.java. 
+ *
+ * @param env
+ *    
+ * @param ID
+ *    the identifier in octave_ref_map, 
+ *    signifying either a cell array or a function handle. 
+ * @param args
+ *    arguments of the invocation. 
+ */
 JNIEXPORT void JNICALL
-Java_org_octave_Octave_doInvoke (JNIEnv *env, jclass, jint ID,
+Java_org_octave_Octave_doInvoke (JNIEnv *env, 
+                                 jclass, // unneeded? 
+                                 jint ID,
                                  jobjectArray args)
 {
   std::map<int,octave_value>::iterator it = octave_ref_map.find (ID);
@@ -1766,6 +2178,17 @@
     }
 }
 
+/**
+ * Wraps eval_string(cmd, false,...). 
+ * <p>
+ * This method defines 
+ * the call to 
+ * native org.octave.Octave#doEvalString(String). 
+ * defined in scripts/org/octave/Octave.java. 
+ *
+ * @param cmd
+ *    the command to be evaluated. 
+ */
 JNIEXPORT void JNICALL
 Java_org_octave_Octave_doEvalString (JNIEnv *env, jclass, jstring cmd)
 {
@@ -1774,6 +2197,14 @@
   eval_string (s, false, pstatus, 0);
 }
 
+/**
+ * Return whether octave_thread_ID is the thread id of <code>env</code>. 
+ * <p>
+ * This method defines 
+ * the call to 
+ * native org.octave.Octave#needThreadedInvokation(). 
+ * defined in scripts/org/octave/Octave.java. 
+ */
 JNIEXPORT jboolean JNICALL
 Java_org_octave_Octave_needThreadedInvokation (JNIEnv *env, jclass)
 {
@@ -1848,6 +2279,7 @@
 #endif
 }
 
+// 
 octave_value_list
 octave_java::subsref (const std::string& type,
                       const std::list<octave_value_list>& idx, int nargout)
@@ -2111,8 +2543,30 @@
   return true;
 }
 
+/**
+ * Invoke the java member method with name <code>name</code> 
+ * with arguments <code>args</code> on #java_object. 
+ * This is merely a wrapper 
+ * around <code>org.octave.ClassHelper.invokeMethod</code>, 
+ * enclosed by boxing and unboxing defined by 
+ * #unbox(JNIEnv*,octave_value_list&,jobjectArray_ref&,jobjectArray_ref&) 
+ * and by #box(JNIEnv*, void*, void*). 
+ * It goes into <code>DEFUN (javaMethod,...</code>. 
+ *
+ * @param jni_env_arg
+ *    the JNI environment. 
+ * @param  name
+ *    the name of the method to be invoked. 
+ * @param args
+ *    the arguments passed to method <code>name</code> 
+ * @return
+ *    the result of the invocation of method <code>name</code> 
+ *    with arguments <code>args</code> on #java_object. 
+ * @see #do_javaMethod(std::string&, octave_value_list&)
+ */
 octave_value
-octave_java::do_javaMethod (void *jni_env_arg, const std::string& name,
+octave_java::do_javaMethod (void *jni_env_arg, 
+                            const std::string& name,
                             const octave_value_list& args)
 {
 #if defined (HAVE_JAVA)
@@ -2126,20 +2580,34 @@
       jobjectArray_ref arg_objs (jni_env), arg_types (jni_env);
       if (unbox (jni_env, args, arg_objs, arg_types))
         {
-          jclass_ref helperClass (jni_env, find_octave_class (jni_env, "org/octave/ClassHelper"));
-          jmethodID mID = jni_env->GetStaticMethodID (helperClass, "invokeMethod",
-                                                      "(Ljava/lang/Object;Ljava/lang/String;[Ljava/lang/Object;[Ljava/lang/Class;)Ljava/lang/Object;");
+          jclass_ref helperClass (jni_env, 
+                                  find_octave_class (jni_env, 
+                                                     "org/octave/ClassHelper"));
+          jmethodID mID = jni_env
+            ->GetStaticMethodID (helperClass, 
+                                 "invokeMethod",
+                                 // parameter types 
+                                 "(Ljava/lang/Object;Ljava/lang/String;" 
+                                 "[Ljava/lang/Object;[Ljava/lang/Class;)" 
+                                 "Ljava/lang/Object;");
           jstring_ref methName (jni_env, jni_env->NewStringUTF (name.c_str ()));
-          jobjectArray_ref resObj (jni_env, reinterpret_cast<jobjectArray> (jni_env->CallStaticObjectMethod (helperClass, mID,
-                                                                                                             to_java (), jstring (methName), jobjectArray (arg_objs), jobjectArray (arg_types))));
-          if (resObj)
-            retval = box (jni_env, resObj);
-          else
-            retval = check_exception (jni_env);
-        }
+          jobject resObj = jni_env
+            ->CallStaticObjectMethod(helperClass, 
+                                     mID, 
+                                     to_java (), 
+                                     jstring (methName), 
+                                     jobjectArray (arg_objs), 
+                                     jobjectArray (arg_types));
+          // FIXME: why array???? bug? 
+          jobjectArray_ref resObjArr (jni_env, 
+                                      reinterpret_cast<jobjectArray> (resObj));
+          retval = resObjArr
+            ? box (jni_env, resObjArr)
+            : check_exception (jni_env);
+        } // if (unbox 
 
       octave_set_default_fpucw ();
-    }
+    } // if (jni_env)
 
   return retval;
 
@@ -2157,8 +2625,15 @@
 #endif
 }
 
+/**
+ * Invoke the java member method with name <code>name</code> 
+ * with arguments <code>args</code> on #java_object. 
+ * This is merely a wrapper 
+ * around #do_javaMethod(void*, std::string&, octave_value_list&). 
+ */
 octave_value
-octave_java::do_javaMethod (const std::string& name, const octave_value_list& args)
+octave_java::do_javaMethod (const std::string& name, 
+                            const octave_value_list& args)
 {
 #if defined (HAVE_JAVA)
 
@@ -2177,6 +2652,19 @@
 #endif
 }
 
+/**
+ * Invoke the static java method 
+ * in class named <code>class_name</code> with name <code>name</code> 
+ * to arguments <code>args</code>. 
+ * This is merely a wrapper 
+ * around <code>org.octave.ClassHelper.invokeStaticMethod</code> 
+ * enclosed by boxing and unboxing defined by 
+ * #unbox(JNIEnv*,octave_value_list&,jobjectArray_ref&,jobjectArray_ref&) 
+ * and by #box(JNIEnv*, void*, void*). 
+ * It goes into <code>DEFUN (javaMethod,...</code>. 
+ *
+ * @see #do_javaMethod(std::string&, std::string&, octave_value_list&)
+ */
 octave_value
 octave_java:: do_javaMethod (void *jni_env_arg,
                              const std::string& class_name,
@@ -2194,17 +2682,30 @@
       jobjectArray_ref arg_objs (jni_env), arg_types (jni_env);
       if (unbox (jni_env, args, arg_objs, arg_types))
         {
-          jclass_ref helperClass (jni_env, find_octave_class (jni_env, "org/octave/ClassHelper"));
-          jmethodID mID = jni_env->GetStaticMethodID (helperClass, "invokeStaticMethod",
-                                                      "(Ljava/lang/String;Ljava/lang/String;[Ljava/lang/Object;[Ljava/lang/Class;)Ljava/lang/Object;");
+          jclass_ref helperClass (jni_env, 
+                                  find_octave_class (jni_env, 
+                                                     "org/octave/ClassHelper"));
+          jmethodID mID = jni_env
+            ->GetStaticMethodID (helperClass, 
+                                 "invokeStaticMethod",
+                                 // parameter types 
+                                 "(Ljava/lang/String;Ljava/lang/String;" 
+                                 "[Ljava/lang/Object;[Ljava/lang/Class;)" 
+                                 "Ljava/lang/Object;");
           jstring_ref methName (jni_env, jni_env->NewStringUTF (name.c_str ()));
-          jstring_ref clsName (jni_env, jni_env->NewStringUTF (class_name.c_str ()));
-          jobject_ref resObj (jni_env, jni_env->CallStaticObjectMethod (helperClass, mID,
-                                                                        jstring (clsName), jstring (methName), jobjectArray (arg_objs), jobjectArray (arg_types)));
-          if (resObj)
-            retval = box (jni_env, resObj);
-          else
-            retval = check_exception (jni_env);
+          jstring_ref  clsName (jni_env, jni_env->NewStringUTF 
+                                (class_name.c_str ()));
+          jobject resObj =  jni_env
+            ->CallStaticObjectMethod (helperClass, 
+                                      mID,
+                                      jstring (clsName), 
+                                      jstring (methName), 
+                                      jobjectArray (arg_objs), 
+                                      jobjectArray (arg_types));
+          jobject_ref resObjRef (jni_env, resObj);
+          retval = resObjRef 
+            ? box (jni_env, resObjRef)
+            : check_exception (jni_env);
         }
 
       octave_set_default_fpucw ();
@@ -2227,6 +2728,13 @@
 #endif
 }
 
+/**
+ * Invoke the static java method 
+ * in class named <code>class_name</code> with name <code>name</code> 
+ * to arguments <code>args</code>. 
+ * This is merely a wrapper around 
+ * #do_javaMethod(void*,std::string&,std::string&,octave_value_list&). 
+ */
 octave_value
 octave_java::do_javaMethod (const std::string& class_name,
                             const std::string& name,
@@ -2250,8 +2758,21 @@
 #endif
 }
 
+/**
+ * Call the java constructor in class named <code>name</code> 
+ * with arguments <code>args</code>. 
+ * This is merely a wrapper 
+ * around <code>org.octave.ClassHelper.invokeConstructor</code>, 
+ * enclosed by boxing and unboxing defined by 
+ * #unbox(JNIEnv*,octave_value_list&,jobjectArray_ref&,jobjectArray_ref&) 
+ * and by #box(JNIEnv*, void*, void*). 
+ * It goes into <code>DEFUN (javaObject,...</code>. 
+ *
+ * @see #do_javaObject(std::string&, octave_value_list&)
+ */
 octave_value
-octave_java::do_javaObject (void *jni_env_arg, const std::string& name,
+octave_java::do_javaObject (void *jni_env_arg, 
+                            const std::string& name,
                             const octave_value_list& args)
 {
 #if defined (HAVE_JAVA)
@@ -2266,16 +2787,27 @@
 
       if (unbox (jni_env, args, arg_objs, arg_types))
         {
-          jclass_ref helperClass (jni_env, find_octave_class (jni_env, "org/octave/ClassHelper"));
-          jmethodID mID = jni_env->GetStaticMethodID (helperClass, "invokeConstructor",
-                                                      "(Ljava/lang/String;[Ljava/lang/Object;[Ljava/lang/Class;)Ljava/lang/Object;");
+          jclass_ref helperClass (jni_env, 
+                                  find_octave_class (jni_env, 
+                                                     "org/octave/ClassHelper"));
+          jmethodID mID = jni_env
+            ->GetStaticMethodID (helperClass, 
+                                 "invokeConstructor",
+                                 // parameter types 
+                                 "(Ljava/lang/String;[Ljava/lang/Object;" 
+                                 "[Ljava/lang/Class;)Ljava/lang/Object;");
           jstring_ref clsName (jni_env, jni_env->NewStringUTF (name.c_str ()));
-          jobject_ref resObj (jni_env, jni_env->CallStaticObjectMethod (helperClass, mID,
-                                                                        jstring (clsName), jobjectArray (arg_objs), jobjectArray (arg_types)));
+          jobject resObj = jni_env
+            ->CallStaticObjectMethod (helperClass, 
+                                      mID, 
+                                      jstring (clsName), 
+                                      jobjectArray (arg_objs), 
+                                      jobjectArray (arg_types));
+          jobject_ref resObjRef (jni_env, resObj);
 
           if (resObj)
             retval = octave_value (new octave_java (resObj, 0));
-          else
+          else // Here not 'retval = ' is this a bug??? 
             check_exception (jni_env);
         }
 
@@ -2298,8 +2830,15 @@
 #endif
 }
 
+/**
+ * Call the java constructor in class named <code>name</code> 
+ * with arguments <code>args</code>. 
+ * This is merely a wrapper 
+ * around #do_javaObject(void*, std::string&, octave_value_list&). 
+ */
 octave_value
-octave_java::do_javaObject (const std::string& name, const octave_value_list& args)
+octave_java::do_javaObject (const std::string& name, 
+                            const octave_value_list& args)
 {
 #if defined (HAVE_JAVA)
 
@@ -2318,6 +2857,16 @@
 #endif
 }
 
+/**
+ * Return the value of the java field with name <code>name</code> 
+ * in #java_object. 
+ * This is merely a wrapper 
+ * around the java-method <code>org.octave.ClassHelper.getField</code> 
+ * followed by boxing defined by #box(JNIEnv*, void*, void*). 
+ * It goes into <code>DEFUN (__java_get__,...</code>. 
+ *
+ * @see #do_java_get(std::string&)
+ */
 octave_value
 octave_java::do_java_get (void *jni_env_arg, const std::string& name)
 {
@@ -2329,18 +2878,24 @@
 
   if (jni_env)
     {
-      jclass_ref helperClass (jni_env, find_octave_class (jni_env, "org/octave/ClassHelper"));
-      jmethodID mID = jni_env->GetStaticMethodID (helperClass, "getField",
-          "(Ljava/lang/Object;Ljava/lang/String;)Ljava/lang/Object;");
-      jstring_ref fName (jni_env, jni_env->NewStringUTF (name.c_str ()));
-      jobject_ref resObj (jni_env, jni_env->CallStaticObjectMethod (helperClass, mID,
-          to_java (), jstring (fName)));
-
-      if (resObj)
-        retval = box (jni_env, resObj);
-      else
-        retval = check_exception (jni_env);
-
+      jclass_ref helperClass (jni_env, 
+                              find_octave_class (jni_env, 
+                                                 "org/octave/ClassHelper"));
+      jmethodID mID = jni_env
+        ->GetStaticMethodID (helperClass, 
+                             "getField",
+                              // parameter types 
+                             "(Ljava/lang/Object;Ljava/lang/String;)"
+                             "Ljava/lang/Object;");
+      jstring_ref fName (jni_env,  jni_env->NewStringUTF (name.c_str ()));
+      jobject resObj = jni_env->CallStaticObjectMethod 
+        (helperClass, mID, to_java (), jstring (fName));
+      jobject_ref resObjRef (jni_env, resObj);
+  
+      retval = resObjRef
+        ? box (jni_env, resObjRef)
+        : check_exception (jni_env);
+ 
       octave_set_default_fpucw ();
     }
 
@@ -2359,6 +2914,12 @@
 #endif
 }
 
+/**
+ * Return the value of the java field with name <code>name</code> 
+ * in #java_object. 
+ * This is merely a wrapper 
+ * around #do_java_get(void*, std::string&). 
+ */
 octave_value
 octave_java::do_java_get (const std::string& name)
 {
@@ -2378,8 +2939,19 @@
 #endif
 }
 
+/**
+ * Return the value of the static java field 
+ * in class named <code>class_name</code> with name <code>name</code>. 
+ * This is merely a wrapper 
+ * around <code>org.octave.ClassHelper.getStaticField</code> 
+ * followed by boxing defined by #box(JNIEnv*, void*, void*). 
+ * It goes into <code>DEFUN (__java_get__,...</code>. 
+ *
+ * @see #do_java_get(std::string&, std::string&)
+ */
 octave_value
-octave_java::do_java_get (void *jni_env_arg, const std::string& class_name,
+octave_java::do_java_get (void *jni_env_arg, 
+                          const std::string& class_name,
                           const std::string& name)
 {
 #if defined (HAVE_JAVA)
@@ -2390,18 +2962,24 @@
 
   if (jni_env)
     {
-      jclass_ref helperClass (jni_env, find_octave_class (jni_env, "org/octave/ClassHelper"));
-      jmethodID mID = jni_env->GetStaticMethodID (helperClass, "getStaticField",
-          "(Ljava/lang/String;Ljava/lang/String;)Ljava/lang/Object;");
+      jclass_ref helperClass (jni_env, 
+                              find_octave_class (jni_env, 
+                                                 "org/octave/ClassHelper"));
+      jmethodID mID = jni_env
+        ->GetStaticMethodID (helperClass, 
+                             "getStaticField",
+                             // parameter types 
+                             "(Ljava/lang/String;Ljava/lang/String;)"
+                             "Ljava/lang/Object;");
       jstring_ref cName (jni_env, jni_env->NewStringUTF (class_name.c_str ()));
       jstring_ref fName (jni_env, jni_env->NewStringUTF (name.c_str ()));
-      jobject_ref resObj (jni_env, jni_env->CallStaticObjectMethod (helperClass, mID,
-          jstring (cName), jstring (fName)));
-      if (resObj)
-        retval = box (jni_env, resObj);
-      else
-        retval = check_exception (jni_env);
-
+      jobject_ref resObj (jni_env, jni_env->CallStaticObjectMethod 
+                          (helperClass, mID, jstring (cName), jstring (fName)));
+
+      retval = resObj
+        ? box (jni_env, resObj)
+        : check_exception (jni_env);
+ 
       octave_set_default_fpucw ();
     }
 
@@ -2421,8 +2999,15 @@
 #endif
 }
 
+/**
+ * Return the value of the static java field 
+ * in class named <code>class_name</code> with name <code>name</code>. 
+ * This is merely a wrapper 
+ * around #do_java_get(void*, std::string&, std::string&). 
+ */
 octave_value
-octave_java::do_java_get (const std::string& class_name, const std::string& name)
+octave_java::do_java_get (const std::string& class_name, 
+                          const std::string& name)
 {
 #if defined (HAVE_JAVA)
 
@@ -2441,36 +3026,51 @@
 #endif
 }
 
-octave_value
-octave_java::do_java_set (void *jni_env_arg, const std::string& name,
+/**
+ * Set the value of the java field with name <code>name</code> 
+ * in #java_object with value <code>val</code>. 
+ * This is merely a wrapper 
+ * around <code>org.octave.ClassHelper.setField</code> 
+ * preceeded by unboxing defined by 
+ * #unbox(JNIEnv*, octave_value&, jobject_ref&, jobject_ref&). 
+ * It goes into <code>DEFUN (__java_set__,...</code>. 
+ *
+ * @see #do_java_set(std::string&, octave_value&)
+ */
+void
+octave_java::do_java_set (void *jni_env_arg, 
+                          const std::string& name,
                           const octave_value& val)
 {
 #if defined (HAVE_JAVA)
 
-  octave_value retval;
-
   JNIEnv *jni_env = TO_JNIENV (jni_env_arg);
 
   if (jni_env)
     {
       jobject_ref jobj (jni_env);
-      jclass_ref jcls (jni_env);
+      jclass_ref  jcls (jni_env);
 
       if (unbox (jni_env, val, jobj, jcls))
         {
-          jclass_ref helperClass (jni_env, find_octave_class (jni_env, "org/octave/ClassHelper"));
-          jmethodID mID = jni_env->GetStaticMethodID (helperClass, "setField",
-                                                      "(Ljava/lang/Object;Ljava/lang/String;Ljava/lang/Object;)V");
+          jclass_ref helperClass (jni_env, 
+                                  find_octave_class (jni_env, 
+                                                     "org/octave/ClassHelper"));
+          jmethodID mID = jni_env
+            ->GetStaticMethodID (helperClass, 
+                                 "setField",
+                                 // parameter types 
+                                 "(Ljava/lang/Object;Ljava/lang/String;"
+                                 "Ljava/lang/Object;)V");
           jstring_ref fName (jni_env, jni_env->NewStringUTF (name.c_str ()));
-          jni_env->CallStaticObjectMethod (helperClass, mID, to_java (), jstring (fName), jobject (jobj));
+          jni_env->CallStaticObjectMethod 
+            (helperClass, mID, to_java (), jstring (fName), jobject (jobj));
           check_exception (jni_env);
         }
 
       octave_set_default_fpucw ();
     }
 
-  return retval;
-
 #else
 
   octave_unused_parameter (jni_env_arg);
@@ -2485,12 +3085,18 @@
 #endif
 }
 
-octave_value
+/**
+ * Set the value of the java field with name <code>name</code> 
+ * in #java_object with value <code>val</code>. 
+ * This is merely a wrapper 
+ * around #do_java_set(void*, std::string&, octave_value&). 
+ */
+void
 octave_java::do_java_set (const std::string& name, const octave_value& val)
 {
 #if defined (HAVE_JAVA)
 
-  return do_java_set (thread_jni_env (), name, val);
+  do_java_set (thread_jni_env (), name, val);
 
 #else
 
@@ -2505,37 +3111,57 @@
 #endif
 }
 
-octave_value
-octave_java::do_java_set (void *jni_env_arg, const std::string& class_name,
-                          const std::string& name, const octave_value& val)
+/**
+ * Set the value of the static java field 
+ * in class named <code>class_name</code> with name <code>name</code> 
+ * with value <code>val</code>. 
+ * This is merely a wrapper 
+ * around <code>org.octave.ClassHelper.setStaticField</code> 
+ * preceeded by unboxing defined by 
+ * #unbox(JNIEnv*, octave_value&, jobject_ref&, jobject_ref&).  
+ * It goes into <code>DEFUN (__java_set__,...</code>. 
+ *
+ * @see #do_java_set(std::string&, octave_value&)
+ */
+void
+octave_java::do_java_set (void *jni_env_arg, 
+                          const std::string& class_name,
+                          const std::string& name, 
+                          const octave_value& val)
 {
 #if defined (HAVE_JAVA)
 
-  octave_value retval;
-
   JNIEnv *jni_env = TO_JNIENV (jni_env_arg);
 
   if (jni_env)
     {
       jobject_ref jobj (jni_env);
-      jclass_ref jcls (jni_env);
+      jclass_ref  jcls (jni_env);
 
       if (unbox (jni_env, val, jobj, jcls))
         {
-          jclass_ref helperClass (jni_env, find_octave_class (jni_env, "org/octave/ClassHelper"));
-          jmethodID mID = jni_env->GetStaticMethodID (helperClass, "setStaticField",
-                                                      "(Ljava/lang/String;Ljava/lang/String;Ljava/lang/Object;)V");
+          jclass_ref helperClass (jni_env, 
+                                  find_octave_class (jni_env, 
+                                                     "org/octave/ClassHelper"));
+          jmethodID mID = jni_env
+            ->GetStaticMethodID (helperClass, 
+                                 "setStaticField",
+                                 // parameter types 
+                                 "(Ljava/lang/String;Ljava/lang/String;"
+                                 "Ljava/lang/Object;)V");
           jstring_ref cName (jni_env, jni_env->NewStringUTF (class_name.c_str ()));
           jstring_ref fName (jni_env, jni_env->NewStringUTF (name.c_str ()));
-          jni_env->CallStaticObjectMethod (helperClass, mID, jstring (cName), jstring (fName), jobject (jobj));
+          jni_env->CallStaticObjectMethod (helperClass, 
+                                           mID, 
+                                           jstring (cName), 
+                                           jstring (fName), 
+                                           jobject (jobj));
           check_exception (jni_env);
         }
 
       octave_set_default_fpucw ();
     }
 
-  return retval;
-
 #else
 
   octave_unused_parameter (jni_env_arg);
@@ -2551,13 +3177,21 @@
 #endif
 }
 
-octave_value
-octave_java::do_java_set (const std::string& class_name, const std::string& name,
+/**
+ * Set the value of the static java field 
+ * in class named <code>class_name</code> with name <code>name</code> 
+ * with value <code>val</code>. 
+ * This is merely a wrapper 
+ * around #do_java_set(void*, std::string&, octave_value&). 
+ */
+void
+octave_java::do_java_set (const std::string& class_name, 
+                          const std::string& name,
                           const octave_value& val)
 {
 #if defined (HAVE_JAVA)
 
-  return do_java_set (thread_jni_env (), class_name, name, val);
+  do_java_set (thread_jni_env (), class_name, name, val);
 
 #else
 
@@ -2579,7 +3213,7 @@
 #if defined (HAVE_JAVA)
 
   jobject jobj = TO_JOBJECT (jobj_arg);
-  jclass jcls = TO_JCLASS (jcls_arg);
+  jclass  jcls = TO_JCLASS  (jcls_arg);
 
   JNIEnv *current_env = thread_jni_env ();
 
@@ -2592,15 +3226,21 @@
         java_class = current_env->NewGlobalRef (jcls);
       else if (java_object)
         {
-          jclass_ref ocls (current_env, current_env->GetObjectClass (TO_JOBJECT (java_object)));
+          jclass_ref ocls(current_env, 
+                          current_env->GetObjectClass(TO_JOBJECT(java_object)));
           java_class = current_env->NewGlobalRef (jclass (ocls));
         }
 
       if (java_class)
         {
-          jclass_ref clsCls (current_env, current_env->GetObjectClass (TO_JCLASS (java_class)));
-          jmethodID mID = current_env->GetMethodID (clsCls, "getCanonicalName", "()Ljava/lang/String;");
-          jobject_ref resObj (current_env, current_env->CallObjectMethod (TO_JCLASS (java_class), mID));
+          jclass_ref clsCls(current_env, 
+                            current_env->GetObjectClass(TO_JCLASS(java_class)));
+          jmethodID mID = current_env->GetMethodID (clsCls, 
+                                                    "getCanonicalName", 
+                                                    "()Ljava/lang/String;");
+          jobject_ref resObj (current_env, 
+                              current_env->CallObjectMethod 
+                              (TO_JCLASS (java_class), mID));
           java_classname = jstring_to_string (current_env, resObj);
         }
     }
@@ -2699,11 +3339,16 @@
 #endif
 }
 
+/**
+ * Defines call to java constructors. 
+ * Accordingly, this is based on 
+ * #do_javaObject(void*, std::string&, octave_value_list&)). 
+ */
 DEFUN (javaObject, args, ,
        doc: /* -*- texinfo -*-
 @deftypefn  {} {@var{jobj} =} javaObject (@var{classname})
 @deftypefnx {} {@var{jobj} =} javaObject (@var{classname}, @var{arg1}, @dots{})
-Create a Java object of class @var{classsname}, by calling the class
+Create a Java object of class @var{classname}, by calling the class
 constructor with the arguments @var{arg1}, @dots{}
 
 The first example below creates an uninitialized object, while the second
@@ -2724,7 +3369,8 @@
   if (args.length () == 0)
     print_usage ();
 
-  std::string classname = args(0).xstring_value ("javaObject: CLASSNAME must be a string");
+  std::string classname = args(0)
+    .xstring_value ("javaObject: CLASSNAME must be a string");
 
   initialize_java ();
 
@@ -2754,6 +3400,12 @@
 %! assert (javaObject ("java.lang.Short", 40000).doubleValue < 0);
 */
 
+/**
+ * Defines invocation of java methods, both static ones and member methods. 
+ * Accordingly, this is based on 
+ * #do_javaMethod(void*, std::string&, octave_value_list&)) and on 
+ * #do_javaMethod(void*, std::string&, std::string&, octave_value_list&).  
+ */
 DEFUN (javaMethod, args, ,
        doc: /* -*- texinfo -*-
 @deftypefn  {} {@var{ret} =} javaMethod (@var{methodname}, @var{obj})
@@ -2785,7 +3437,8 @@
   if (args.length () < 2)
     print_usage ();
 
-  std::string methodname = args(0).xstring_value ("javaMethod: METHODNAME must be a string");
+  std::string methodname = args(0)
+    .xstring_value ("javaMethod: METHODNAME must be a string");
 
   initialize_java ();
 
@@ -2828,6 +3481,12 @@
 %! assert (isfinite (str2double (jver{1})) && isfinite (str2double (jver{2})));
 */
 
+/**
+ * Return the value of java fields, both static ones and member fields. 
+ * Accordingly, this is based on 
+ * #do_java_get(void*, std::string&) and on 
+ * #do_java_get(void*, std::string&, std::string&). 
+ */
 DEFUN (__java_get__, args, ,
        doc: /* -*- texinfo -*-
 @deftypefn {} {@var{val} =} __java_get__ (@var{obj}, @var{name})
@@ -2855,7 +3514,8 @@
   if (args.length () != 2)
     print_usage ();
 
-  std::string name = args(1).string_value ("__java_get__: NAME must be a string");
+  std::string name = args(1)
+    .string_value ("__java_get__: NAME must be a string");
 
   initialize_java ();
 
@@ -2887,11 +3547,16 @@
 #endif
 }
 
+/**
+ * Set the value of java fields, both static ones and member fields. 
+ * Accordingly, this is based on 
+ * #do_java_set(void*, std::string&, octave_value&) and on 
+ * #do_java_set(void*, std::string&, std::string&, octave_value&). 
+ */
 DEFUN (__java_set__, args, ,
        doc: /* -*- texinfo -*-
 @deftypefn {} {@var{obj} =} __java_set__ (@var{obj}, @var{name}, @var{val})
-Set the value of the field @var{name} of the Java object @var{obj} to
-@var{val}.
+Set the value of the field @var{name} of the Java object @var{obj} to @var{val}.
 
 For static fields, @var{obj} can be a string representing the fully
 qualified named of the corresponding Java class.
@@ -2915,7 +3580,8 @@
   if (args.length () != 3)
     print_usage ();
 
-  std::string name = args(1).xstring_value ("__java_set__: NAME must be a string");
+  std::string name = args(1)
+    .xstring_value ("__java_set__: NAME must be a string");
 
   initialize_java ();
 
@@ -2926,12 +3592,12 @@
   if (args(0).is_java ())
     {
       octave_java *jobj = TO_JAVA (args(0));
-      retval = jobj->do_java_set (current_env, name, args(2));
+      jobj->do_java_set (current_env, name, args(2));
     }
   else if (args(0).is_string ())
     {
       std::string cls = args(0).string_value ();
-      retval = octave_java::do_java_set (current_env, cls, name, args(2));
+      octave_java::do_java_set (current_env, cls, name, args(2));
     }
   else
     error ("__java_set__: OBJ must be a Java object or a string");
