From bbdc7966db8152940d6f73db75dc99eb79fa754f Mon Sep 17 00:00:00 2001
From: Yorick Peterse <yorickpeterse@gmail.com>
Date: Wed, 7 May 2014 10:24:24 +0200
Subject: [PATCH] Documentation for the JRuby extension.

---
 ext/java/LibogaService.java      | 14 +++++++++++++
 ext/java/org/liboga/xml/Lexer.rl | 35 ++++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/ext/java/LibogaService.java b/ext/java/LibogaService.java
index c19e12a..9bf79dc 100644
--- a/ext/java/LibogaService.java
+++ b/ext/java/LibogaService.java
@@ -8,6 +8,20 @@ import org.jruby.runtime.load.Library;
 
 public class LibogaService implements BasicLibraryService
 {
+    /**
+     * Bootstraps the JRuby extension.
+     *
+     * In order to load this extension properly you have to make sure that the
+     * lib/ directory is in the Ruby load path. If this is the case you can
+     * load it as following:
+     *
+     *     require 'liboga'
+     *
+     * Using absolute paths (e.g. with `require_relative`) requires you to
+     * manually call this method:
+     *
+     *     LibogaService.new.basicLoad(JRuby.runtime)
+     */
     public boolean basicLoad(final Ruby runtime) throws IOException
     {
         org.liboga.xml.Lexer.load(runtime);
diff --git a/ext/java/org/liboga/xml/Lexer.rl b/ext/java/org/liboga/xml/Lexer.rl
index d68bc11..52b3f4f 100644
--- a/ext/java/org/liboga/xml/Lexer.rl
+++ b/ext/java/org/liboga/xml/Lexer.rl
@@ -18,13 +18,27 @@ import org.jruby.runtime.ThreadContext;
 import org.jruby.runtime.ObjectAllocator;
 import org.jruby.runtime.builtin.IRubyObject;
 
+/**
+ * Lexer support class for JRuby.
+ *
+ * The Lexer class contains the raw Ragel loop and calls back in to Ruby land
+ * whenever a Ragel action is needed similar to the C extension setup.
+ *
+ * This class requires Ruby land to first define the `Oga::XML` namespace.
+ */
 @JRubyClass(name="Oga::XML::Lexer", parent="Object")
 public class Lexer extends RubyObject
 {
+    /**
+     * The current Ruby runtime.
+     */
     private Ruby runtime;
 
     %% write data;
 
+    /**
+     * Sets up the current class in the Ruby runtime.
+     */
     public static void load(Ruby runtime)
     {
         RubyModule xml = (RubyModule) runtime.getModule("Oga")
@@ -54,6 +68,16 @@ public class Lexer extends RubyObject
         this.runtime = runtime;
     }
 
+    /**
+     * Runs the bulk of the Ragel loop and calls back in to Ruby.
+     *
+     * This method pulls its data in from the instance variable `@data`. The
+     * Ruby side of the Lexer class should set this variable to a String in its
+     * constructor method. Encodings are passed along to make sure that token
+     * values share the same encoding as the input.
+     *
+     * This method always returns nil.
+     */
     @JRubyMethod
     public IRubyObject advance_native(ThreadContext context)
     {
@@ -72,6 +96,7 @@ public class Lexer extends RubyObject
         int eof = data.length;
         int top = 0;
 
+        // Fixed stack size of 8 should be more than enough.
         int[] stack = new int[8];
 
         %% write init;
@@ -80,6 +105,13 @@ public class Lexer extends RubyObject
         return context.nil;
     }
 
+    /**
+     * Calls back in to Ruby land passing the current token value along.
+     *
+     * This method calls back in to Ruby land based on the method name
+     * specified in `name`. The Ruby callback should take one argument. This
+     * argument will be a String containing the value of the current token.
+     */
     public void callback(String name, byte[] data, Encoding enc, int ts, int te)
     {
         ByteList bytelist = new ByteList(data, ts, te - ts, enc, true);
@@ -91,6 +123,9 @@ public class Lexer extends RubyObject
         this.callMethod(context, name, value);
     }
 
+    /**
+     * Calls back in to Ruby land without passing any arguments.
+     */
     public void callback_simple(String name)
     {
         ThreadContext context = this.runtime.getCurrentContext();