Here is some documentation of java_field for the wiki (enclosed as a diff, as I couldn't find a better way to supply wiki changes as part of a pull request). I did not succeed in writing, and testing, a similar one for add_field_annotation. I don't know why my attempts failed, but I do have one question: what should add_field_annotation do if passed a name which does not exist? It seems to silently fail now.

diff --git a/GeneratingJavaClasses.md b/GeneratingJavaClasses.md
index 7c0d088..0921838 100644
--- a/GeneratingJavaClasses.md
+++ b/GeneratingJavaClasses.md
@@ -39,6 +39,25 @@ end

 The resulting Java class has an instance method named ```some_method``` and a static method named ```class_method```.

+Similarly, you can add java fields:
+
+```
+class Bar
+  java_field "java.lang.String name"
+  become_java!
+end
+b = Bar.new
+b.name = "chin-up"
+b.name
+# =>
+# "chin-up"
+b.name = 234
+# raises IllegalArgumentException
+```
+
+The type of a Java field currently must be a non-primitive type (for example, java.lang.Object not int).
+
+
 Generating Java Classes Ahead-of-time
 -------------------------------------

[Note: I made comment on 48938ee which would be nice to be addressed]

I find this a reasonable starting point and I think we can merge this as-is, but I feel this is an incomplete feature as it would be nice if we could use the equivalent of java_signature() instead of the more procedural mechanism we have in place. It would see a day where we can have:

java_field '@Persistent @Synchronized Integer baz'

I suspect JavaSignatureParser needs some work to process field signatures but it is my hope eventually the above signature is the only way we add stuff. I mostly mention this is anyone wants to look into JavaSignatureParser and allow a more cut-and-paste signature format.

I'm going to go ahead and merge this, since it seems like a good start. I agree with @enebo that we should (with your help) continue to build out this functionality and also try to expand tests to more complex cases.