Added and updated comments / docs

jni/SafeArray.cpp

@@ -54,6 +54,9 @@ static SAFEARRAY *makeArray(int vt, int nDims, long *lb, long *cel)
   }
 }
 
+/**
+ * extracts the Variant from the int pointer in the java object
+ */
 VARIANT *extractWrapper(JNIEnv *env, jobject arg)
 {
   jclass argClass = env->GetObjectClass(arg);
@@ -1156,6 +1159,8 @@ JNIEXPORT jobjectArray JNICALL Java_com_jacob_com_SafeArray_toVariantArray
 
 // this is an ugly way to avoid copy/pasting the same code
 
+// returns a value extracted from a 1 dimensional SafeArray
+// uses the idx variable in the object this macro is included in 
 #define GET1DCODE(varType, varAccess, jtyp) \
   SAFEARRAY *sa = extractSA(env, _this); \
   if (!sa) { \
@@ -1185,6 +1190,8 @@ JNIEXPORT jobjectArray JNICALL Java_com_jacob_com_SafeArray_toVariantArray
     return NULL; \
   }
 
+// returns a value extracted from a 2 dimensional SafeArray
+// uses i and j from the method that this macro is included in as indexes
 #define GET2DCODE(varType, varAccess, jtyp) \
   SAFEARRAY *sa = extractSA(env, _this); \
   if (!sa) { \
@@ -1216,6 +1223,7 @@ JNIEXPORT jobjectArray JNICALL Java_com_jacob_com_SafeArray_toVariantArray
   }
 
 
+// sets the values on a one dimensional array 
 #define SET1DCODE(varType, varAccess) \
   SAFEARRAY *sa = extractSA(env, _this); \
   if (!sa) { \
@@ -1240,6 +1248,7 @@ JNIEXPORT jobjectArray JNICALL Java_com_jacob_com_SafeArray_toVariantArray
     ThrowComFail(env, "safearray type mismatch", -1); \
   } \
 
+// sets the values into a 2 dimensional array
 #define SET2DCODE(varType, varAccess) \
   SAFEARRAY *sa = extractSA(env, _this); \
   if (!sa) { \

src/com/jacob/com/SafeArray.java

@@ -319,50 +319,51 @@ public class SafeArray extends JacobObject {
     public native void setChars(int sa_idx, int nelems, char ja[], int ja_start);
 
     /**
-     * int access
-     * @param sa_idx
+     * get int from an single dimensional array
+     * @param sa_idx array index
      * @return int stored in array
      */
     public native int getInt(int sa_idx);
 
     /**
-     * int access
-     * @param sa_idx1
-     * @param sa_idx2
+     * get int from 2 dimensional array
+     * @param sa_idx1 array index first dimension
+     * @param sa_idx2 array index of second dimension
      * @return int stored in array
      */
     public native int getInt(int sa_idx1, int sa_idx2);
 
     /**
-     * int access
-     * @param sa_idx
-     * @param c
+     * sets the int value of an element in a single dimensional array
+     * @param sa_idx index into the array
+     * @param c the value to be set
      */
     public native void setInt(int sa_idx, int c);
 
     /**
-     * int access
-     * @param sa_idx1
-     * @param sa_idx2
-     * @param c
+     * sets the int value of a 2 dimensional array
+     * @param sa_idx1 index on the first dimension
+     * @param sa_idx2 index on the second dimension
+     * @param c the value to be set
      */
     public native void setInt(int sa_idx1, int sa_idx2, int c);
 
     /**
-     * int access
-     * @param sa_idx
-     * @param nelems
-     * @param ja
-     * @param ja_start
+     * retrieves a group of ints from a single dimensional array
+     * 
+     * @param sa_idx the index in the array to start the get
+     * @param nelems number of elements to retrieve
+     * @param ja the structure to be filled with the ints
+     * @param ja_start the start point in the java int array to start filling
      */
     public native void getInts(int sa_idx, int nelems, int ja[], int ja_start);
 
     /**
-     * int access
-     * @param sa_idx
-     * @param nelems
-     * @param ja
-     * @param ja_start
+     * sets a group of ints into a single dimensional array
+     * @param sa_idx the index of the start of the array to put into
+     * @param nelems number of elements to be copied
+     * @param ja the new int values to be put into the array
+     * @param ja_start the start index in the array that we are copying into SafeArray
      */
     public native void setInts(int sa_idx, int nelems, int ja[], int ja_start);