From 0218b56949a20152412e40887368e96298b3477d Mon Sep 17 00:00:00 2001
From: Greg <gmp@wow.st>
Date: Tue, 23 Jun 2020 13:12:05 -0400
Subject: [PATCH] Documentation.

---
 jni.go | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/jni.go b/jni.go
index 49cf026..e347ba6 100644
--- a/jni.go
+++ b/jni.go
@@ -43,12 +43,21 @@ type (
 	Value     uint64 // All JNI types fit into 64-bits.
 )
 
+const (
+	TRUE C.JNI_TRUE
+	FALSE C.JNI_FALSE
+)
+
+// JVMFor creates a JVM object, interpreting the given uintptr as a pointer
+// to a C.JavaVM object.
 func JVMFor(jvmPtr uintptr) JVM {
 	return JVM{
 		jvm: (*C.JavaVM)(unsafe.Pointer(jvmPtr)),
 	}
 }
 
+// EnvFor creates an Env object, interpreting the given uintptr as a pointer
+// to a C.JNIEnv object.
 func EnvFor(envPtr uintptr) Env {
 	return Env{
 		env: (*C.JNIEnv)(unsafe.Pointer(envPtr)),
@@ -81,18 +90,22 @@ func varArgs(args []Value) *C.jvalue {
 	return (*C.jvalue)(unsafe.Pointer(&args[0]))
 }
 
+// IsSameObject returns true if the two given objects refer to the same
+// Java object.
 func IsSameObject(e Env, ref1, ref2 Object) bool {
 	same := C._jni_IsSameObject(e.env, C.jobject(ref1), C.jobject(ref2))
 	return same == C.JNI_TRUE
 }
 
+// CallStaticIntMethod calls a static method on a Java class, returning an int.
 func CallStaticIntMethod(e Env, cls Class, method MethodID, args ...Value) (int, error) {
 	res := C._jni_CallStaticIntMethodA(e.env, C.jclass(cls), C.jmethodID(method), varArgs(args))
 	return int(res), exception(e)
 }
 
-// FindClass finds a class with a given name, using the JVM's default
-// class loader.
+// FindClass returns a reference to a Java class with a given name, using the
+// JVM's default class loader. Any exceptions caused by the underlying JNI call
+// (for example if the class is not found) will result in a panic.
 func FindClass(e Env, name string) Class {
 	mname := C.CString(name)
 	defer C.free(unsafe.Pointer(mname))
@@ -103,33 +116,40 @@ func FindClass(e Env, name string) Class {
 	return Class(res)
 }
 
-// NewObject creates a new object given a class, initializer methodID, and
-// arguments (if any).
+// NewObject creates a new object given a class, initializer method, and
+// initializer arguments (if any).
 func NewObject(e Env, cls Class, method MethodID, args ...Value) (Object, error) {
 	res := C._jni_NewObjectA(e.env, C.jclass(cls), C.jmethodID(method), varArgs(args))
 	return Object(res), exception(e)
 }
 
+// CallStaticVoidMethod calls a static method on a Java class, returning
+// nothing.
 func CallStaticVoidMethod(e Env, cls Class, method MethodID, args ...Value) error {
 	C._jni_CallStaticVoidMethodA(e.env, C.jclass(cls), C.jmethodID(method), varArgs(args))
 	return exception(e)
 }
 
+// CallVoidMethod calls a method on an object, returning nothing.
 func CallVoidMethod(e Env, obj Object, method MethodID, args ...Value) error {
 	C._jni_CallVoidMethodA(e.env, C.jobject(obj), C.jmethodID(method), varArgs(args))
 	return exception(e)
 }
 
+// CallStaticObjectMethod calls a static method on a class, returning a
+// Java object
 func CallStaticObjectMethod(e Env, cls Class, method MethodID, args ...Value) (Object, error) {
 	res := C._jni_CallStaticObjectMethodA(e.env, C.jclass(cls), C.jmethodID(method), varArgs(args))
 	return Object(res), exception(e)
 }
 
+// CallObjectMethod calls a method on an object, returning a Java object.
 func CallObjectMethod(e Env, obj Object, method MethodID, args ...Value) (Object, error) {
 	res := C._jni_CallObjectMethodA(e.env, C.jobject(obj), C.jmethodID(method), varArgs(args))
 	return Object(res), exception(e)
 }
 
+// CallIntMethod calls a method on an object, returning an int32.
 func CallIntMethod(e Env, obj Object, method MethodID, args ...Value) (int32, error) {
 	res := C._jni_CallIntMethodA(e.env, C.jobject(obj), C.jmethodID(method), varArgs(args))
 	return int32(res), exception(e)