Add javadoc content to source files.

build.xml

@@ -5,6 +5,7 @@
 	
 	<property name="jar.name.jme" value="luaj-jme-${version}.jar"/>
 	<property name="jar.name.jse" value="luaj-jse-${version}.jar"/>
+	<property name="jar.name.jse.sources" value="luaj-jse.sources-${version}.jar"/>
 
 	<import file="wtk.xml"/>
 
@@ -130,6 +131,12 @@
 		</jar>
 	</target>
 
+	<target name="jar-jse-sources" depends="compile">
+		<jar destfile="${jar.name.jse.sources}">
+		    <fileset dir="build/jse/src"/>
+		</jar>
+	</target>
+
 	<target name="doc">
 		<delete dir="docs/api"/>
 		<mkdir dir="docs/api"/>
@@ -190,6 +197,6 @@
 			basedir="build" includes="luaj-${version}/**"/>
 	</target>
 	
-	<target name="all" depends="clean,jar-jme,jar-jse"/>
+	<target name="all" depends="clean,jar-jme,jar-jse,jar-jse-sources"/>
 		
 </project>

src/core/org/luaj/vm2/LoadState.java

@@ -25,14 +25,44 @@ import java.io.DataInputStream;
 import java.io.IOException;
 import java.io.InputStream;
 
+
 /**
 * Class to manage loading of {@link Prototype} instances.
 * <p>
+* The {@link LoadState} class exposes one main function, 
+* namely {@link #load(InputStream, String, LuaValue)}, 
+* to be used to load code from a particular input stream.  
+* <p>
+* A simple pattern for loading and executing code is
+* <pre> {@code
+* LuaValue _G = JsePlatform.standardGlobals();
+* LoadState.load( new FileInputStream("main.lua"), "main.lua", _G ).call();
+* } </pre>
+* This should work regardless of which {@link LuaCompiler}
+* has been installed.
+* <p>
+*  
+* Prior to loading code, a compiler should be installed. 
+* <p>
+* By default, when using {@link JsePlatform} or {@JmePlatform}
+* to construct globals, the {@link LuaC} compiler is installed. 
+* <p>
+* To override the default compiler with, say, the {@link LuaJC}
+* lua-to-java bytecode compiler, install it before loading, 
+* for example:
+* <pre> {@code
+* LuaValue _G = JsePlatform.standardGlobals();
+* LuaJC.install();
+* LoadState.load( new FileInputStream("main.lua"), "main.lua", _G ).call();
+* } </pre>
+* 
 * @see LuaCompiler
 * @see LuaClosure
 * @see LuaFunction
 * @see LoadState#compiler
 * @see LoadState#load(InputStream, String, LuaValue)
+* @see LuaC
+* @see LuaJC
 */
 public class LoadState {
 	

src/core/org/luaj/vm2/LuaFunction.java

@@ -28,6 +28,9 @@ package org.luaj.vm2;
  * all built-in library functions coded in Java, 
  * and {@link LuaClosure}, which represents a lua closure 
  * whose bytecode is interpreted when the function is invoked.    
+ * @see LuaValue
+ * @see LibFunction
+ * @see LuaClosure
  */
 abstract
 public class LuaFunction extends LuaValue {

src/core/org/luaj/vm2/LuaNil.java

@@ -34,7 +34,8 @@ package org.luaj.vm2;
  * the recommended approach is to use the method {@link LuaValue#isnil()} 
  * instead.  By using that any ambiguities between 
  * {@link LuaValue#NIL} and {@link LuaValue#NONE} are avoided.
- * 
+ * @see LuaValue
+ * @see LuaValue#NIL
  */
 public class LuaNil extends LuaValue {
 	

src/core/org/luaj/vm2/LuaNumber.java

@@ -28,6 +28,7 @@ package org.luaj.vm2;
  * and {@link LuaDouble} which holds all other number values.
  * @see LuaInteger
  * @see LuaDouble
+ * @see LuaValue
  * 
  */
 abstract

src/core/org/luaj/vm2/LuaTable.java

@@ -60,11 +60,14 @@ import java.util.Vector;
  * <ul>
  * <li>{@link LuaValue#tableOf()} empty table</li>
  * <li>{@link LuaValue#tableOf(int, int)} table with capacity</li>
- * <li>{@link LuaValue#tableOf(LuaValue[])} initialize array part</li>
+ * <li>{@link LuaValue#listOf(LuaValue[])} initialize array part</li>
- * <li>{@link LuaValue#tableOf(Varargs, int)} initialize array part</li>
+ * <li>{@link LuaValue#listOf(LuaValue[], Varargs)} initialize array part</li>
+ * <li>{@link LuaValue#tableOf(LuaValue[])} initialize named hash part</li>
+ * <li>{@link LuaValue#tableOf(Varargs, int)} initialize named hash part</li>
  * <li>{@link LuaValue#tableOf(LuaValue[], LuaValue[])} initialize array and named parts</li>
  * <li>{@link LuaValue#tableOf(LuaValue[], LuaValue[], Varargs)} initialize array and named parts</li>
  * </ul>
+ * @see LuaValue
  */
 public class LuaTable extends LuaValue {
 	private static final int      MIN_HASH_CAPACITY = 2;

src/core/org/luaj/vm2/LuaThread.java

@@ -23,10 +23,38 @@ package org.luaj.vm2;
 
 import org.luaj.vm2.lib.DebugLib;
 
-
-
 /** 
- * Implementation of lua coroutines using Java Threads
+ * Subclass of {@link LuaValue} that implements 
+ * a lua coroutine thread using Java Threads.
+ * <p>
+ * A LuaThread is typically created in response to a scripted call to 
+ * {@code coroutine.create()}
+ * <p>
+ * The threads must be initialized with the globals, so that 
+ * the global environment may be passed along according to rules of lua. 
+ * This is done via a call to {@link #setGlobals(LuaValue)} 
+ * at some point during globals initialization.
+ * See {@link BaseLib} for additional documentation and example code.  
+ * <p> 
+ * The utility classes {@link JsePlatform} and {@link JmePlatform} 
+ * see to it that this initialization is done properly.  
+ * For this reason it is highly recommended to use one of these classes
+ * when initializing globals. 
+ * <p>
+ * The behavior of coroutine threads matches closely the behavior 
+ * of C coroutine library.  However, because of the use of Java threads 
+ * to manage call state, it is possible to yield from anywhere in luaj. 
+ * On the other hand, if a {@link LuaThread} is created, then yields 
+ * without ever entering a completed state, then the garbage collector 
+ * may not be able to determine that the thread needs to be collected, 
+ * and this could cause a memory and resource leak.  It is recommended
+ * that all coroutines that are created are resumed until they are in 
+ * a completed state. 
+ *   
+ * @see LuaValue
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see CoroutineLib
  */
 public class LuaThread extends LuaValue implements Runnable {
 	
@@ -68,6 +96,11 @@ public class LuaThread extends LuaValue implements Runnable {
 	LuaThread() {		
 	}
 	
+	/** 
+	 * Create a LuaThread around a function and environment
+	 * @param func The function to execute
+	 * @param env The environment to apply to the thread
+	 */
 	public LuaThread(LuaValue func, LuaValue env) {	
 		this.env = env;
 		this.func = func;
@@ -109,37 +142,66 @@ public class LuaThread extends LuaValue implements Runnable {
 		return STATUS_NAMES[status];
 	}
 
+	/**
+	 * Get the currently running thread. 
+	 * @return {@link LuaThread} that is currenly running
+	 */
 	public static LuaThread getRunning() {
 		return running_thread;
 	}
 	
+	/**
+	 * Test if this is the main thread 
+	 * @return true if this is the main thread
+	 */
 	public static boolean isMainThread(LuaThread r) {		
 		return r == mainthread;
 	}
 	
-	/** Set the globals of the current thread */
+	/** 
+	 * Set the globals of the current thread.
+	 * <p>
+	 * This must be done once before any other code executes.
+	 * @param globals The global variables for the main ghread. 
+	 */
 	public static void setGlobals(LuaValue globals) {
 		running_thread.env = globals;
 	}
 	
-	/** Get the current thread's environment */
+	/** Get the current thread's environment 
+	 * @return {@link LuaValue} containing the global variables of the current thread.
+	 */
 	public static LuaValue getGlobals() {
 		LuaValue e = running_thread.env;
 		return e!=null? e: LuaValue.error("LuaThread.setGlobals() not initialized");
 	}
 
+	/**
+	 * Callback used at the beginning of a call
+	 * @param function Function being called
+	 * @see DebugLib
+	 */
 	public static final void onCall(LuaFunction function) {
 		running_thread.callstack[running_thread.calls++] = function;
 		if (DebugLib.DEBUG_ENABLED) 
 			DebugLib.debugOnCall(running_thread, running_thread.calls, function);
 	}
 	
+	/**
+	 * Callback used at the end of a call
+	 * @see DebugLib
+	 */
 	public static final void onReturn() {
 		running_thread.callstack[--running_thread.calls] = null;
 		if (DebugLib.DEBUG_ENABLED) 
 			DebugLib.debugOnReturn(running_thread, running_thread.calls);
 	}
 
+	/**
+	 * Get number of calls in stack
+	 * @return number of calls in current call stack
+	 * @see DebugLib
+	 */
 	public static int getCallstackDepth() {
 		return running_thread.calls;
 	}
@@ -170,6 +232,11 @@ public class LuaThread extends LuaValue implements Runnable {
 		}
 	}
 	
+	/** Yield this thread with arguments 
+	 * 
+	 * @param args The arguments to send as return values to {@link #resume(Varargs)}
+	 * @return {@link Varargs} provided as arguments to {@link #resume(Varargs)}
+	 */
 	public Varargs yield(Varargs args) {
 		synchronized ( this ) {
 			if ( status != STATUS_RUNNING )
@@ -189,7 +256,11 @@ public class LuaThread extends LuaValue implements Runnable {
 		}
 	}
 
-	/** Start or resume this thread */
+	/** Start or resume this thread 
+	 * 
+	 * @param args The arguments to send as return values to {@link #yield(Varargs)}
+	 * @return {@link Varargs} provided as arguments to {@link #yield(Varargs)}
+	 */
 	public Varargs resume(Varargs args) {
 
 		synchronized ( this ) {

src/core/org/luaj/vm2/LuaValue.java

@@ -29,22 +29,12 @@ package org.luaj.vm2;
  * This allows Java clients to deal essentially with one type for all Java values, namely {@link LuaValue}.
  * <p>
  * Constructors are provided as static methods for common Java types, such as 
- * {@link LuaValue#valueOf(int)} or {@link LuaValue#valueOf(String)}.  
+ * {@link LuaValue#valueOf(int)} or {@link LuaValue#valueOf(String)} 
- * Primarily this is used to encourage instance pooling for small integers or short strings. 
+ * to allow for instance pooling. 
  * <p> 
  * Constants are defined for the lua values 
- * {@link LuaValue#NIL}, {@link LuaValue#TRUE}, and {@link LuaValue#FALSE}. 
+ * {@link #NIL}, {@link #TRUE}, and {@link #FALSE}. 
- * A constant {@link LuaValue#NONE} is defined which is a {@link Varargs} list having no values.  
+ * A constant {@link #NONE} is defined which is a {@link Varargs} list having no values.
- * Predefined constants exist for the standard lua type constants 
- * {@link TNIL}, {@link TBOOLEAN}, {@link TLIGHTUSERDATA}, {@link TNUMBER}, {@link TSTRING}, 
- * {@link TTABLE}, {@link TFUNCTION}, {@link TUSERDATA}, {@link TTHREAD},
- * extended lua type constants 
- * {@link TINT}, {@link TNONE}, {@link TVALUE},
- * as well as for the  metatags  
- * {@link INDEX}, {@link NEWINDEX}, {@link CALL}, {@link MODE}, {@link METATABLE},   
- * {@link ADD}, {@link SUB}, {@link DIV}, {@link MUL}, {@link POW},   
- * {@link MOD}, {@link UNM}, {@link LEN}, {@link EQ}, {@link LT},   
- * {@link LE}, {@link TOSTRING}, {@link CONCAT} as well as 
  * <p> 
  * Operations are performed on values directly via their Java methods.  
  * For example, the following code divides two numbers:
@@ -75,16 +65,47 @@ package org.luaj.vm2;
  * print.call( r.arg(1), r.arg(2) );
  * } </pre>
  * <p>
+ * To load and run a script, {@link LoadState} is used:
+ * <pre> {@code
+ * LoadState.load( new FileInputStream("main.lua"), "main.lua", globals ).call();
+ * } </pre>
+ * <p>
+ * although {@code require} could also be used: 
+ * <pre> {@code
+ * globals.get("require").call(LuaValue.valueOf("main"));
+ * } </pre>
+ * For this to work the file must be in the current directory, or in the class path, 
+ * dependening on the platform.  
+ * See {@link JsePlatform} and {@link JmePlatform} for details. 
+ * <p>
  * In general a {@link LuaError} may be thrown on any operation when the  
  * types supplied to any operation are illegal from a lua perspective. 
  * Examples could be attempting to concatenate a NIL value, or attempting arithmetic 
  * on values that are not number.  
  * <p>
- * When a {@link LuaTable} is required by an api, a table constructor such as {@link tableOf()} 
+ * There are several methods for preinitializing tables, such as:
- * can be used, or the type may be coerced via {@link checktable()} or {@link opttable(LuaValue)}.
+ * <ul>
- * Constructors exist to create pre-initialized tables such as {@link LuaValue#tableOf(LuaValue[])} 
+ * <li>{@link #listOf(LuaValue[])} for unnamed elements</li>
- * for lists, {@link LuaValue#tableOf(LuaValue[], LuaValue[])} for hashtables, 
+ * <li>{@link #tableOf(LuaValue[])} for named elements</li>
- * or {@link LuaValue#tableOf(LuaValue[], LuaValue[], Varargs)} for mixed tables.   
+ * <li>{@link #tableOf(LuaValue[], LuaValue[], Varargs)} for mixtures</li>
+ * </ul>
+ * <p>  
+ * Predefined constants exist for the standard lua type constants 
+ * {@link TNIL}, {@link TBOOLEAN}, {@link TLIGHTUSERDATA}, {@link TNUMBER}, {@link TSTRING}, 
+ * {@link TTABLE}, {@link TFUNCTION}, {@link TUSERDATA}, {@link TTHREAD},
+ * and extended lua type constants 
+ * {@link TINT}, {@link TNONE}, {@link TVALUE}
+ * <p> 
+ * Predefined constants exist for all strings used as metatags:  
+ * {@link INDEX}, {@link NEWINDEX}, {@link CALL}, {@link MODE}, {@link METATABLE},   
+ * {@link ADD}, {@link SUB}, {@link DIV}, {@link MUL}, {@link POW},   
+ * {@link MOD}, {@link UNM}, {@link LEN}, {@link EQ}, {@link LT},   
+ * {@link LE}, {@link TOSTRING}, and {@link CONCAT}.
+ * 
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see LoadState 
+ * @see Varargs
  */
 abstract
 public class LuaValue extends Varargs {

src/core/org/luaj/vm2/Varargs.java

@@ -37,13 +37,13 @@ package org.luaj.vm2;
  * such as  {@code LuaValue.varargsOf(LuaValue,Varargs)}
  * or by taking a portion of the args using {@code Varargs.subargs(int start)}
  * <p>
- * @see org.luaj.vm2.LuaValue#varargsOf(LuaValue[])
+ * @see LuaValue#varargsOf(LuaValue[])
- * @see org.luaj.vm2.LuaValue#varargsOf(LuaValue, Varargs)
+ * @see LuaValue#varargsOf(LuaValue, Varargs)
- * @see org.luaj.vm2.LuaValue#varargsOf(LuaValue[], Varargs)
+ * @see LuaValue#varargsOf(LuaValue[], Varargs)
- * @see org.luaj.vm2.LuaValue#varargsOf(LuaValue, LuaValue, Varargs)
+ * @see LuaValue#varargsOf(LuaValue, LuaValue, Varargs)
- * @see org.luaj.vm2.LuaValue#varargsOf(LuaValue[], int, int)
+ * @see LuaValue#varargsOf(LuaValue[], int, int)
- * @see org.luaj.vm2.LuaValue#varargsOf(LuaValue[], int, int, Varargs)
+ * @see LuaValue#varargsOf(LuaValue[], int, int, Varargs)
- * @see org.luaj.vm2.LuaValue#subargs(int)
+ * @see LuaValue#subargs(int)
  */
 public abstract class Varargs {
 

src/core/org/luaj/vm2/compiler/LuaC.java

@@ -36,7 +36,6 @@ import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Prototype;
 import org.luaj.vm2.LoadState.LuaCompiler;
 
-
 /**
  * Compiler for Lua.
  * <p>
@@ -49,6 +48,20 @@ import org.luaj.vm2.LoadState.LuaCompiler;
  * initialized chunks, which is an interface common to 
  * lua bytecode compiling and java bytecode compiling. 
  * <p> 
+ * Teh {@link LuaC} compiler is installed by default by both the 
+ * {@link JsePlatform} and {@link JmePlatform} classes, 
+ * so in the following example, the default {@link LuaC} compiler 
+ * will be used:
+ * <pre> {@code
+ * LuaValue _G = JsePlatform.standardGlobals();
+ * LoadState.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
+ * } </pre>
+ * @see LuaCompiler
+ * @see LuaJC
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see BaseLib
+ * @see LuaValue
  * @see LuaCompiler
  * @see Prototype
  */

src/core/org/luaj/vm2/lib/BaseLib.java

@@ -33,19 +33,41 @@ import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
 /** 
- * Base library implementation, targeted for JME platforms.
+ * Subclass of {@link LibFunction} which implements the lua basic library functions. 
- * 
+ * <p>
- * BaseLib instances are typically used as the initial globals table 
+ * This contains all library functions listed as "basic functions" in the lua documentation for JME. 
- * when creating a new uniqued runtime context.  
+ * The functions dofile and loadfile use the 
- * 
+ * {@link #FINDER} instance to find resource files.
- * Since JME has no file system by default, dofile and loadfile use the 
+ * Since JME has no file system by default, {@link BaseLib} implements 
- * FINDER instance to find resource files.  The default loader chain
+ * {@link ResourceFinder} using {@link Class#getResource(String)}, 
- * in PackageLib will use these as well.  
+ * which is the closest equivalent on JME.     
- * 
+ * The default loader chain in {@link PackageLib} will use these as well.
- * For an implementation that looks in the current directory on JSE, 
+ * <p>  
- * use org.luaj.lib.j2se.BaseLib instead.
+ * To use basic library functions that include a {@link ResourceFinder} based on 
- *  
+ * directory lookup, use {@link JseBaseLib} instead. 
- * @see org.luaj.vm2.lib.jse.JseBaseLib
+ * <p>
+ * Typically, this library is included as part of a call to either 
+ * {@link JmePlatform#standardGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new BaseLib());
+ * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * } </pre>
+ * Doing so will ensure the library is properly initialized 
+ * and loaded into the globals table. 
+ * <p>
+ * This is a direct port of the corresponding library in C.
+ * @see JseBaseLib
+ * @see ResourceFinder
+ * @see #FINDER
+ * @see LibFunction
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.1">http://www.lua.org/manual/5.1/manual.html#5.1</a>
  */
 public class BaseLib extends OneArgFunction implements ResourceFinder {
 	public static final String VERSION = "Luaj 2.0";

src/core/org/luaj/vm2/lib/CoroutineLib.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (c) 2007 LuaJ. All rights reserved.
+* Copyright (c) 2007-2011 LuaJ. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
@@ -26,6 +26,34 @@ import org.luaj.vm2.LuaThread;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
+/** 
+ * Subclass of {@link LibFunction} which implements the lua standard {@code coroutine} 
+ * library. 
+ * <p> 
+ * The coroutine library in luaj has the same behavior as the
+ * coroutine library in C, but is implemented using Java Threads to maintain 
+ * the call state between invocations.  Therefore it can be yielded from anywhere, 
+ * similar to the "Coco" yield-from-anywhere patch available for C-based lua.
+ * However, coroutines that are yielded but never resumed to complete their execution
+ * may not be collected by the garbage collector. 
+ * <p> 
+ * Typically, this library is included as part of a call to either 
+ * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * _G.load(new CoroutineLib());
+ * } </pre>
+ * Doing so will ensure the library is properly initialized 
+ * and loaded into the globals table. 
+ * <p>
+ * @see LibFunction
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.2">http://www.lua.org/manual/5.1/manual.html#5.2</a>
+ */
 public class CoroutineLib extends VarArgFunction {
 	
 	private static final int INIT    = 0;

src/core/org/luaj/vm2/lib/DebugLib.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
@@ -36,6 +36,34 @@ import org.luaj.vm2.Print;
 import org.luaj.vm2.Prototype;
 import org.luaj.vm2.Varargs;
 
+/** 
+ * Subclass of {@link LibFunction} which implements the lua standard {@code debug} 
+ * library. 
+ * <p> 
+ * The debug library in luaj tries to emulate the behavior of the corresponding C-based lua library.
+ * To do this, it must maintain a separate stack of calls to {@link LuaClosure} and {@link LibFunction} 
+ * instances.  
+ * Especially when lua-to-java bytecode compiling is being used
+ * via a {@link LuaCompiler} such as {@link LuaJC}, 
+ * this cannot be done in all cases.  
+ * <p> 
+ * Typically, this library is included as part of a call to either 
+ * {@link JsePlatform#debugGlobals()} or {@link JmePlatform#debugGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * _G.load(new DebugLib());
+ * } </pre>
+ * Doing so will ensure the library is properly initialized 
+ * and loaded into the globals table. 
+ * <p>
+ * @see LibFunction
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.9">http://www.lua.org/manual/5.1/manual.html#5.9</a>
+ */
 public class DebugLib extends VarArgFunction {
 	public static final boolean CALLS = (null != System.getProperty("CALLS"));
 	public static final boolean TRACE = (null != System.getProperty("TRACE"));

src/core/org/luaj/vm2/lib/IoLib.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
@@ -30,8 +30,45 @@ import org.luaj.vm2.LuaTable;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
-
+/** 
-
+ * Abstract base class extending {@link LibFunction} which implements the 
+ * core of the lua standard {@code io} library.   
+ * <p> 
+ * It contains the implementation of the io library support that is common to
+ * the JSE and JME platforms. 
+ * In practice on of the concrete IOLib subclasses is chosen:  
+ * {@link org.luaj.vm2.lib.jse.JseIoLib} for the JSE platform, and 
+ * {@link org.luaj.vm2.lib.jme.JmeIoLib} for the JME platform.
+ * <p>
+ * The JSE implementation conforms almost completely to the C-based lua library, 
+ * while the JME implementation follows closely except in the area of random-access files, 
+ * which are difficult to support properly on JME. 
+ * <p> 
+ * Typically, this library is included as part of a call to either 
+ * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * _G.load(new JseIoLib());
+ * LuaThread.setGlobals(_G);
+ * _G.load(new JseBaseLib());
+ * _G.load(new PackageLib());
+ * _G.load(new JseIoLib());
+ * _G.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
+ * } </pre>
+ * Doing so will ensure the library is properly initialized 
+ * and loaded into the globals table. 
+ * <p>
+ * This has been implemented to match as closely as possible the behavior in the corresponding library in C.
+ * @see LibFunction
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see JseIoLib
+ * @see JmeIoLib
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.7">http://www.lua.org/manual/5.1/manual.html#5.7</a>
+ */
 abstract 
 public class IoLib extends OneArgFunction {
 

src/core/org/luaj/vm2/lib/LibFunction.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
@@ -25,11 +25,112 @@ import org.luaj.vm2.LuaError;
 import org.luaj.vm2.LuaFunction;
 import org.luaj.vm2.LuaValue;
 
+/**
+ * Subclass of {@link LuaFunction} common to Java functions exposed to lua. 
+ * <p>
+ * To provide for common implementations in JME and JSE, 
+ * library functions are typically grouped on one or more library classes
+ * and an opcode per library function is defined and used to key the switch
+ * to the correct function within the library.  
+ * <p>
+ * Since lua functions can be called with too few or too many arguments, 
+ * and there are overloaded {@link LuaValue#call()} functions with varying 
+ * number of arguments, a Java function exposed in lua needs to handle  the
+ * argument fixup when a function is called with a number of arguments 
+ * differs from that expected.  
+ * <p>
+ * To simplify the creation of library functions, 
+ * there are 5 direct subclasses to handle common cases based on number of 
+ * argument values and number of return return values.
+ * <ul>
+ * <li>{@link ZeroArgFunction}</li>
+ * <li>{@link OneArgFunction}</li>
+ * <li>{@link TwoArgFunction}</li>
+ * <li>{@link ThreeArgFunction}</li>
+ * <li>{@link VarArgFunction}</li>
+ * </ul>
+ * <p>
+ * To be a Java library that can be loaded via {@code require}, it should have 
+ * a public constructor that returns a {@link LuaValue} that, when executed, 
+ * initializes the library. 
+ * <p> 
+ * For example, the following code will implement a library called "hyperbolic" 
+ * with two functions, "sinh", and "cosh":
+ * <pre> {@code 
+ * import org.luaj.vm2.LuaValue;
+ * public class hyperbolic extends org.luaj.vm2.lib.OneArgFunction {
+ * 	public hyperbolic() {}
+ * 	public LuaValue call(LuaValue arg) {
+ * 		switch ( opcode ) {
+ * 		case 0: {
+ * 			LuaValue t = tableOf();
+ * 			this.bind(t, hyperbolic.class, new String[] { "sinh", "cosh" }, 1 );
+ * 			env.set("hyperbolic", t);
+ * 			return t;
+ * 		}
+ * 		case 1: return valueOf(Math.sinh(arg.todouble()));
+ * 		case 2: return valueOf(Math.cosh(arg.todouble()));
+ * 		default: return error("bad opcode: "+opcode);
+ * 		}
+ * 	}
+ * } 
+ * }</pre>
+ * The default constructor is both to instantiate the library 
+ * in response to {@code require 'hyperbolic'} statement, 
+ * provided it is on Javas class path, 
+ * and to instantiate copies of the {@code hyperbolic} 
+ * class when initializing library instances. . 
+ * The instance returned by the default constructor will be invoked
+ * as part of library loading.  
+ * In response, it creates two more instances, one for each library function,  
+ * in the body of the {@code switch} statement {@code case 0} 
+ * via the {@link #bind(LuaValue, Class, String[], int)} utility method.
+ * It also registers the table in the globals via the {@link #env} 
+ * local variable, which should be the global environment unless 
+ * it has been changed.
+ * {@code case 1} and {@code case 2} will be called when {@code hyperbolic.sinh}
+ * {@code hyperbolic.sinh} and {@code hyperbolic.cosh} are invoked. 
+ * <p>
+ * To test it, a script such as this can be used:
+ * <pre> {@code
+ * local t = require('hyperbolic')
+ * print( 't', t )
+ * print( 'hyperbolic', hyperbolic )
+ * for k,v in pairs(t) do
+ * 	print( 'k,v', k,v )
+ * end
+ * print( 'sinh(.5)', hyperbolic.sinh(.5) )
+ * print( 'cosh(.5)', hyperbolic.cosh(.5) )
+ * }</pre> 
+ * <p>
+ * It should produce something like:
+ * <pre> {@code
+ * t	table: 3dbbd23f
+ * hyperbolic	table: 3dbbd23f
+ * k,v	cosh	cosh
+ * k,v	sinh	sinh
+ * sinh(.5)	0.5210953
+ * cosh(.5)	1.127626
+ * }</pre> 
+ * <p> 
+ * See the source code in any of the library functions 
+ * such as {@link BaseLib} or {@link TableLib} for specific examples.  
+ */
 abstract public class LibFunction extends LuaFunction {
 	
+	/** User-defined opcode to differentiate between instances of the library function class. 
+	 * <p>
+	 * Subclass will typicall switch on this value to provide the specific behavior for each function. 
+	 */
 	protected int opcode;
+	
+	/** The common name for this function, useful for debugging.
+	 * <p>
+	 * Binding functions initialize this to the name to which it is bound.
+	 */
 	protected String name;
 	
+	/** Default constructor for use by subclasses */
 	protected LibFunction() {		
 	}
 	
@@ -37,10 +138,31 @@ abstract public class LibFunction extends LuaFunction {
 		return name != null? name: super.tojstring();
 	}
 	
+	/** 
+	 * Bind a set of library functions.  
+	 * <p>
+	 * An array of names is provided, and the first name is bound 
+	 * with opcode = 0, second with 1, etc. 
+	 * @param env The environment to apply to each bound function 
+	 * @param factory the Class to instantiate for each bound function
+	 * @param names array of String names, one for each function.
+	 * @see #bind(LuaValue, Class, String[], int)  
+	 */
 	protected void bind(LuaValue env, Class factory,  String[] names ) {
 		bind( env, factory, names, 0 );
 	}
 	
+	/** 
+	 * Bind a set of library functions, with an offset  
+	 * <p>
+	 * An array of names is provided, and the first name is bound 
+	 * with opcode = {@code firstopcode}, second with {@code firstopcode+1}, etc. 
+	 * @param env The environment to apply to each bound function 
+	 * @param factory the Class to instantiate for each bound function
+	 * @param names array of String names, one for each function.
+	 * @param firstopcode the first opcode to use  
+	 * @see #bind(LuaValue, Class, String[])  
+	 */
 	protected void bind(LuaValue env, Class factory,  String[] names, int firstopcode ) {
 		try {
 			for ( int i=0, n=names.length; i<n; i++ ) {
@@ -55,17 +177,17 @@ abstract public class LibFunction extends LuaFunction {
 		}
 	}	
 
-	// allocate storage for upvalue, leave it empty
+	/** Java code generation utility to allocate storage for upvalue, leave it empty */
 	protected static LuaValue[] newupe() {
 		return new LuaValue[1];
 	}
 
-	// allocate storage for upvalue, initialize with nil
+	/** Java code generation utility to allocate storage for upvalue, initialize with nil */
 	protected static LuaValue[] newupn() {
 		return new LuaValue[] { NIL };
 	}
 	
-	// allocate storage for upvalue, initialize with value
+	/** Java code generation utility to allocate storage for upvalue, initialize with value */
 	protected static LuaValue[] newupl(LuaValue v) {
 		return new LuaValue[] { v };
 	}

src/core/org/luaj/vm2/lib/MathLib.java

@@ -29,11 +29,50 @@ import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
 /** 
- * Base math library with JME support.  
+ * Subclass of {@link LibFunction} which implements the lua standard {@code math} 
- * 
+ * library. 
- * For j2se support use org.luaj.lib.j2se.MathLib
+ * <p> 
- * 
+ * It contains only the math library support that is possible on JME.  
- * @see org.luaj.vm2.lib.jse.JseMathLib
+ * For a more complete implementation based on math functions specific to JSE 
+ * use {@link org.luaj.vm2.lib.jse.JseMathLib}. 
+ * In Particular the following math functions are <b>not</b> implemented by this library:
+ * <ul>
+ * <li>acos</li>
+ * <li>asin</li>
+ * <li>atan</li>
+ * <li>cosh</li>
+ * <li>log</li>
+ * <li>log10</li>
+ * <li>sinh</li>
+ * <li>tanh</li>
+ * <li>atan2</li>
+ * </ul>
+ * <p>
+ * The implementations of {@code exp()} and {@code pow()} are constructed by 
+ * hand for JME, so will be slower and less accurate than when executed on the JSE platform.
+ * <p> 
+ * Typically, this library is included as part of a call to either 
+ * {@link JmePlatform#standardGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new BaseLib());
+ * _G.load(new PackageLib());
+ * _G.load(new MathLib());
+ * System.out.println( _G.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
+ * } </pre>
+ * Doing so will ensure the library is properly initialized 
+ * and loaded into the globals table. 
+ * <p>
+ * This has been implemented to match as closely as possible the behavior in the corresponding library in C.
+ * @see LibFunction
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see JseMathLib
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.6">http://www.lua.org/manual/5.1/manual.html#5.6</a>
  */
 public class MathLib extends OneArgFunction {
 	

src/core/org/luaj/vm2/lib/OneArgFunction.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
@@ -24,13 +24,39 @@ package org.luaj.vm2.lib;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
+/** Abstract base class for Java function implementations that take one argument and 
+ * return one value. 
+ * <p>
+ * Subclasses need only implement {@link LuaValue#call(LuaValue)} to complete this class, 
+ * simplifying development.  
+ * All other uses of {@link #call()}, {@link #invoke(Varargs)},etc, 
+ * are routed through this method by this class, 
+ * dropping or extending arguments with {@code nil} values as required.
+ * <p>
+ * If more than one argument are required, or no arguments are required, 
+ * or variable argument or variable return values, 
+ * then use one of the related function
+ * {@link ZeroArgFunction}, {@link TwoArgFunction}, {@link ThreeArgFunction}, or {@link VarArgFunction}.
+ * <p>
+ * See {@link LibFunction} for more information on implementation libraries and library functions.
+ * @see #call(LuaValue)
+ * @see LibFunction
+ * @see ZeroArgFunction
+ * @see TwoArgFunction
+ * @see ThreeArgFunction
+ * @see VarArgFunction
+ */
 abstract public class OneArgFunction extends LibFunction {
 
 	abstract public LuaValue call(LuaValue arg);
 	
+	/** Default constructor */
 	public OneArgFunction() {
 	}
 	
+	/** Constructor with specific environment
+	 * @param env The environment to apply during constructon.
+	 */
 	public OneArgFunction( LuaValue env ) {
 		this.env = env;
 	}

src/core/org/luaj/vm2/lib/OsLib.java

@@ -28,23 +28,49 @@ import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
 /**
- * Base implementation of OsLib, with simplified stub functions
+ * Subclass of {@link LibFunction} which implements the standard lua {@code os} library.
+ * <p>
+ * It is a usable base with simplified stub functions
  * for library functions that cannot be implemented uniformly 
  * on Jse and Jme.   
- * 
  * <p>
  * This can be installed as-is on either platform, or extended 
  * and refined to be used in a complete Jse implementation.
- * 
+ * <p>
- * <p>Contains limited implementations of features not supported well on Jme:
+ * Because the nature of the {@code os} library is to encapsulate 
- * <bl>
+ * os-specific features, the behavior of these functions varies considerably 
- * <li>execute()</li>
+ * from their counterparts in the C platform.  
- * <li>remove()</li>
+ * <p>
- * <li>rename()</li>
+ * The following functions have limited implementations of features 
- * <li>tmpname()</li>
+ * that are not supported well on Jme:
- * </bl>
+ * <ul>
- *
+ * <li>{@code execute()}</li>
- * @see org.luaj.vm2.lib.jse.JseOsLib
+ * <li>{@code remove()}</li>
+ * <li>{@code rename()}</li>
+ * <li>{@code tmpname()}</li>
+ * </ul>
+ * <p>
+ * Typically, this library is included as part of a call to either 
+ * {@link JmePlatform#standardGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new BaseLib());
+ * _G.load(new PackageLib());
+ * _G.load(new OsLib());
+ * System.out.println( _G.get("os").get("time").call() );
+ * } </pre>
+ * Doing so will ensure the library is properly initialized 
+ * and loaded into the globals table. 
+ * <p>
+  * @see LibFunction
+ * @see JseOsLib
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.8">http://www.lua.org/manual/5.1/manual.html#5.8</a>
  */
 public class OsLib extends VarArgFunction {
 	public static String TMP_PREFIX    = ".luaj";

src/core/org/luaj/vm2/lib/PackageLib.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (c) 2010 Luaj.org. All rights reserved.
+* Copyright (c) 2010-2011 Luaj.org. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
@@ -31,7 +31,38 @@ import org.luaj.vm2.LuaThread;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
-
+/** 
+ * Subclass of {@link LibFunction} which implements the lua standard package and module 
+ * library functions. 
+ * 
+ * <p>
+ * Typically, this library is included as part of a call to either 
+ * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new BaseLib());
+ * _G.load(new PackageLib());
+ * System.out.println( _G.get("require").call(LuaValue.valueOf("hyperbolic")) );
+ * } </pre>
+ * In practice, the first 4 lines of the above are minimal requirements to get 
+ * and initialize a globals table capable of basic reqire, print, and other functions, 
+ * so it is much more convenient to use the {@link JsePlatform} and {@link JmePlatform} 
+ * utility classes instead.  
+ * <p>
+ * This has been implemented to match as closely as possible the behavior in the corresponding library in C.
+ * However, the default filesystem search semantics are different and delegated to the bas library 
+ * as outlined in the {@link BaseLib} and {@link JseBaseLib} documetnation. 
+ * @see LibFunction
+ * @see BaseLib
+ * @see JseBaseLib
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.3">http://www.lua.org/manual/5.1/manual.html#5.3</a>
+ */
 public class PackageLib extends OneArgFunction {
 
 	public static String DEFAULT_LUA_PATH = "?.lua";

src/core/org/luaj/vm2/lib/ResourceFinder.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2009 Luaj.org. All rights reserved.
+ * Copyright (c) 2009-2011 Luaj.org. All rights reserved.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -25,15 +25,22 @@ import java.io.InputStream;
 
 /** 
  * Interface for opening application resource files such as scripts sources.  
- * 
+ * <p>
  * This is used by required to load files that are part of 
  * the application, and implemented by BaseLib
  * for both the Jme and Jse platforms. 
- * 
+ * <p>
- * The Jme version implements FileOpener via getResourceAsStream(), 
+ * The Jme version of base lib {@link BaseLib} 
- * while the Jse version implements it using new File().
+ * implements {@link BaseLib#FINDER} via {@link Class#getResourceAsStream(String)}, 
- * 
+ * while the Jse version {@link JseBaseLib} implements it using {@link java.io.File#File(String)}.
+ * <p>
  * The io library does not use this API for file manipulation.
+ * <p>
+ * @see BaseLib
+ * @see BaseLib#FINDER
+ * @see JseBaseLib
+ * @see JmePlatform
+ * @see JsePlatform 
  */
 public interface ResourceFinder {
 	

src/core/org/luaj/vm2/lib/StringLib.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
@@ -32,6 +32,33 @@ import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 import org.luaj.vm2.compiler.DumpState;
 
+/** 
+ * Subclass of {@link LibFunction} which implements the lua standard {@code string} 
+ * library. 
+ * 
+ * <p>
+ * Typically, this library is included as part of a call to either 
+ * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new BaseLib());
+ * _G.load(new PackageLib());
+ * _G.load(new StringLib());
+ * System.out.println( _G.get("string").get("upper").call( LuaValue.valueOf("abcde") ) );
+ * } </pre>
+ * Doing so will ensure the library is properly initialized 
+ * and loaded into the globals table. 
+ * <p>
+ * This is a direct port of the corresponding library in C.
+ * @see LibFunction
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.4">http://www.lua.org/manual/5.1/manual.html#5.4</a>
+ */
 public class StringLib extends OneArgFunction {
 
 	public static LuaTable instance;

src/core/org/luaj/vm2/lib/TableLib.java

@@ -25,6 +25,37 @@ import org.luaj.vm2.LuaTable;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
+/** 
+ * Subclass of {@link LibFunction} which implements the lua standard {@code table} 
+ * library. 
+ * 
+ * <p>
+ * Typically, this library is included as part of a call to either 
+ * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new BaseLib());
+ * _G.load(new PackageLib());
+ * _G.load(new TableLib());
+ * LuaValue tbl = LuaValue.listOf( new LuaValue[] {
+ * 		LuaValue.valueOf( "abc" ),
+ * 		LuaValue.valueOf( "def" ) } );
+ * LuaValue sep = LuaValue.valueOf( "-" );
+ * System.out.println( _G.get("table").get("concat").call( tbl, sep ) );
+ * } </pre>
+ * Doing so will ensure the library is properly initialized 
+ * and loaded into the globals table. 
+ * <p>
+ * This has been implemented to match as closely as possible the behavior in the corresponding library in C.
+ * @see LibFunction
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.5">http://www.lua.org/manual/5.1/manual.html#5.5</a>
+ */
 public class TableLib extends OneArgFunction {
 
 	public TableLib() {

src/core/org/luaj/vm2/lib/ThreeArgFunction.java

@@ -24,13 +24,39 @@ package org.luaj.vm2.lib;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
+/** Abstract base class for Java function implementations that take two arguments and 
+ * return one value. 
+ * <p>
+ * Subclasses need only implement {@link LuaValue#call(LuaValue,LuaValue,LuaValue)} to complete this class, 
+ * simplifying development.  
+ * All other uses of {@link #call()}, {@link #invoke(Varargs)},etc, 
+ * are routed through this method by this class, 
+ * dropping or extending arguments with {@code nil} values as required.
+ * <p>
+ * If more or less than three arguments are required,  
+ * or variable argument or variable return values, 
+ * then use one of the related function
+ * {@link ZeroArgFunction}, {@link OneArgFunction}, {@link TwoArgFunction}, or {@link VarArgFunction}.
+ * <p>
+ * See {@link LibFunction} for more information on implementation libraries and library functions.
+ * @see #call(LuaValue,LuaValue,LuaValue)
+ * @see LibFunction
+ * @see ZeroArgFunction
+ * @see OneArgFunction
+ * @see TwoArgFunction
+ * @see VarArgFunction
+ */
 abstract public class ThreeArgFunction extends LibFunction {
 
 	abstract public LuaValue call(LuaValue arg1, LuaValue arg2, LuaValue arg3);
 	
+	/** Default constructor */
 	public ThreeArgFunction() {
 	}
 	
+	/** Constructor with specific environment
+	 * @param env The environment to apply during constructon.
+	 */
 	public ThreeArgFunction( LuaValue env ) {
 		this.env = env;
 	}

src/core/org/luaj/vm2/lib/TwoArgFunction.java

@@ -24,13 +24,39 @@ package org.luaj.vm2.lib;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
+/** Abstract base class for Java function implementations that take two arguments and 
+ * return one value. 
+ * <p>
+ * Subclasses need only implement {@link LuaValue#call(LuaValue,LuaValue)} to complete this class, 
+ * simplifying development.  
+ * All other uses of {@link #call()}, {@link #invoke(Varargs)},etc, 
+ * are routed through this method by this class, 
+ * dropping or extending arguments with {@code nil} values as required.
+ * <p>
+ * If more or less than two arguments are required,  
+ * or variable argument or variable return values, 
+ * then use one of the related function
+ * {@link ZeroArgFunction}, {@link OneArgFunction}, {@link ThreeArgFunction}, or {@link VarArgFunction}.
+ * <p>
+ * See {@link LibFunction} for more information on implementation libraries and library functions.
+ * @see #call(LuaValue,LuaValue)
+ * @see LibFunction
+ * @see ZeroArgFunction
+ * @see OneArgFunction
+ * @see ThreeArgFunction
+ * @see VarArgFunction
+ */
 abstract public class TwoArgFunction extends LibFunction {
 
 	abstract public LuaValue call(LuaValue arg1, LuaValue arg2);
 	
+	/** Default constructor */
 	public TwoArgFunction() {
 	}
 	
+	/** Constructor with specific environment
+	 * @param env The environment to apply during constructon.
+	 */
 	public TwoArgFunction( LuaValue env ) {
 		this.env = env;
 	}

src/core/org/luaj/vm2/lib/VarArgFunction.java

@@ -25,6 +25,27 @@ import org.luaj.vm2.LuaThread;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
+/** Abstract base class for Java function implementations that takes varaiable arguments and 
+ * returns multiple return values. 
+ * <p>
+ * Subclasses need only implement {@link LuaValue#invoke(Varargs)} to complete this class, 
+ * simplifying development.  
+ * All other uses of {@link #call(LuaValue)}, {@link #invoke()},etc, 
+ * are routed through this method by this class,
+ * converting arguments to {@linnk Varargs} and  
+ * dropping or extending return values with {@code nil} values as required.
+ * <p>
+ * If between one and three arguments are required, and only one return value is returned,   
+ * {@link ZeroArgFunction}, {@link OneArgFunction}, {@link TwoArgFunction}, or {@link ThreeArgFunction}.
+ * <p>
+ * See {@link LibFunction} for more information on implementation libraries and library functions.
+ * @see #invoke(Varargs)
+ * @see LibFunction
+ * @see ZeroArgFunction
+ * @see OneArgFunction
+ * @see TwoArgFunction
+ * @see ThreeArgFunction
+ */
 abstract public class VarArgFunction extends LibFunction {
 	public VarArgFunction() {
 	}

src/core/org/luaj/vm2/lib/ZeroArgFunction.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
@@ -24,13 +24,37 @@ package org.luaj.vm2.lib;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
+/** Abstract base class for Java function implementations that take no arguments and 
+ * return one value. 
+ * <p>
+ * Subclasses need only implement {@link LuaValue#call()} to complete this class, 
+ * simplifying development.  
+ * All other uses of {@link #call(LuaValue)}, {@link #invoke(Varargs)},etc, 
+ * are routed through this method by this class.
+ * <p>
+ * If one or more arguments are required, or variable argument or variable return values, 
+ * then use one of the related function
+ * {@link OneArgFunction}, {@link TwoArgFunction}, {@link ThreeArgFunction}, or {@link VarArgFunction}.
+ * <p>
+ * See {@link LibFunction} for more information on implementation libraries and library functions.
+ * @see #call()
+ * @see LibFunction
+ * @see OneArgFunction
+ * @see TwoArgFunction
+ * @see ThreeArgFunction
+ * @see VarArgFunction
+ */
 abstract public class ZeroArgFunction extends LibFunction {
 
 	abstract public LuaValue call();
 
+	/** Default constructor */
 	public ZeroArgFunction() {
 	}
 	
+	/** Constructor with specific environment
+	 * @param env The environment to apply during constructon.
+	 */
 	public ZeroArgFunction( LuaValue env ) {
 		this.env = env;
 	}

src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
@@ -29,13 +29,41 @@ import javax.microedition.io.Connector;
 import javax.microedition.io.StreamConnection;
 
 import org.luaj.vm2.LuaString;
+import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.lib.BaseLib;
 import org.luaj.vm2.lib.IoLib;
+import org.luaj.vm2.lib.LibFunction;
 
 /** 
- * Implementation of the lua io library based on CLDC 1.0 and StreamConnection.
+ * Subclass of {@link IoLib} and therefore {@link LibFunction} which implements the lua standard {@code io} 
- * 
+ * library for the JSE platform. 
- * Seek is not supported. 
+ * <p> 
+ * The implementation of the is based on CLDC 1.0 and StreamConnection.
+ * However, seek is not supported. 
+ * <p>
+ * Typically, this library is included as part of a call to 
+ * {@link JmePlatform#standardGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new BaseLib());
+ * _G.load(new PackageLib());
+ * _G.load(new JmeIoLib());
+ * _G.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
+ * } </pre>
+ * Doing so will ensure the library is properly initialized 
+ * and loaded into the globals table. 
+ * <p>
+ * This has been implemented to match as closely as possible the behavior in the corresponding library in C.
+ * @see LibFunction
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see IoLib
+ * @see JseIoLib
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.6">http://www.lua.org/manual/5.1/manual.html#5.6</a>
  */
 public class JmeIoLib extends IoLib {
 	

src/jme/org/luaj/vm2/lib/jme/JmePlatform.java

@@ -22,8 +22,10 @@
 package org.luaj.vm2.lib.jme;
 
 import org.luaj.vm2.compiler.LuaC;
+import org.luaj.vm2.LoadState;
 import org.luaj.vm2.LuaTable;
 import org.luaj.vm2.LuaThread;
+import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.lib.BaseLib;
 import org.luaj.vm2.lib.CoroutineLib;
 import org.luaj.vm2.lib.DebugLib;
@@ -33,12 +35,69 @@ import org.luaj.vm2.lib.PackageLib;
 import org.luaj.vm2.lib.StringLib;
 import org.luaj.vm2.lib.TableLib;
 
+/** The {@link JmePlatform} class is a convenience class to standardize 
+ * how globals tables are initialized for the JME platform. 
+ * <p>
+ * The JME platform, being limited, cannot implement all libraries in all aspects.  The main limitations are
+ * <ul>
+ * <li>Some math functions are not implemented, see {@link MathLib} for details</li>
+ * <li>Scripts are loaded via Class.getResourceAsStream(), see {@link BaseLib} for details</li>
+ * <li>OS functions execute(), remove(), rename(), and tmpname() vary, see {@link OsLib} for details</li>
+ * <li>I/O seek is not implemented, see {@link JmeIoLib} for details</li>
+ * <li>luajava is not available, see {@link LuajavaLib} for details</li>
+ * </ul>
+ * <p>
+ * It is used to allocate either a set of standard globals using 
+ * {@link #standardGlobals()} or debug globals using {@link #debugGlobals()}
+ * <p>
+ * A simple example of initializing globals and using them from Java is:
+ * <pre> {@code
+ * LuaValue _G = JmePlatform.standardGlobals();
+ * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * } </pre>
+ * <p>
+ * Once globals are created, a simple way to load and run a script is:
+ * <pre> {@code
+ * LoadState.load( getClass().getResourceAsStream("main.lua"), "main.lua", _G ).call();
+ * } </pre>
+ * <p>
+ * although {@code require} could also be used: 
+ * <pre> {@code
+ * _G.get("require").call(LuaValue.valueOf("main"));
+ * } </pre>
+ * For this to succeed, the file "main.lua" must be a resource in the class path.
+ * See {@link BaseLib} for details on finding scripts using {@link ResourceFinder}.
+ * <p>
+ * The standard globals will contain all standard libraries in their JME flavors:
+ * <ul>
+ * <li>{@link BaseLib}</li>
+ * <li>{@link PackageLib}</li>
+ * <li>{@link TableLib}</li>
+ * <li>{@link StringLib}</li>
+ * <li>{@link CoroutineLib}</li>
+ * <li>{@link MathLib}</li>
+ * <li>{@link JmeIoLib}</li>
+ * <li>{@link OsLib}</li>
+ * </ul>
+ * In addition, the {@link LuaC} compiler is installed so lua files may be loaded in their source form. 
+ * <p> 
+ * The debug globals are simply the standard globals plus the {@code debug} library {@link DebugLib}.
+ * <p>
+ * <p>
+ * The class ensures that initialization is done in the correct order, 
+ * and that linkage is made  to {@link LuaThread#setGlobals(LuaValue)}. 
+ * @see JsePlatform
+ * @see LoadState
+ */
 public class JmePlatform {
 
 	/**
 	 * Create a standard set of globals for JME including all the libraries.
 	 * 
 	 * @return Table of globals initialized with the standard JME libraries
+	 * @see #debugGlobals()
+	 * @see JsePlatform
+	 * @see JmePlatform
 	 */
 	public static LuaTable standardGlobals() {
 		LuaTable _G = new LuaTable();
@@ -55,6 +114,14 @@ public class JmePlatform {
 		return _G;		
 	}
 	
+	/** Create standard globals including the {@link debug} library.
+	 * 
+	 * @return Table of globals initialized with the standard JSE and debug libraries
+	 * @see #standarsGlobals()
+	 * @see JsePlatform
+	 * @see JmePlatform
+	 * @see DebugLib
+	 */
 	public static LuaTable debugGlobals() {
 		LuaTable _G = standardGlobals();
 		_G.load(new DebugLib());

src/jse/org/luaj/vm2/lib/jse/CoerceJavaToLua.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
@@ -29,7 +29,11 @@ import org.luaj.vm2.LuaInteger;
 import org.luaj.vm2.LuaString;
 import org.luaj.vm2.LuaValue;
 
-
+/**
+ * Helper class to coerce values from Java to lua within the luajava library. 
+ * 
+ * @see LuajavaLib
+ */
 public class CoerceJavaToLua {
 	
 	public static interface Coercion { 

src/jse/org/luaj/vm2/lib/jse/CoerceLuaToJava.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
@@ -29,7 +29,11 @@ import org.luaj.vm2.LuaError;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
-
+/**
+ * Helper class to coerce values from lua to Java within the luajava library. 
+ * 
+ * @see LuajavaLib
+ */
 public class CoerceLuaToJava {
 
 	public static interface Coercion { 

src/jse/org/luaj/vm2/lib/jse/JseBaseLib.java

@@ -26,16 +26,45 @@ import java.io.FileInputStream;
 import java.io.IOException;
 import java.io.InputStream;
 
+import org.luaj.vm2.LuaValue;
+import org.luaj.vm2.lib.BaseLib;
+import org.luaj.vm2.lib.LibFunction;
+import org.luaj.vm2.lib.ResourceFinder;
 
 /** 
- * Base library implementation, targeted for JSE platforms.  
+ * Subclass of {@link BaseLib} and {@link LibFunction} which implements the lua basic library functions
- * 
+ * and provides a directory based {@link ResourceFinder} as the {@link #FINDER}. 
- * Implements the same library functions as org.luaj.lib.BaseLib, 
+ * <p>
- * but looks in the current directory for files loaded via 
+ * Since JME has no file system by default, {@link BaseLib} implements 
- * loadfile(), dofile() and require(). 
+ * {@link ResourceFinder} using {@link Class#getResource(String)}. 
- *  
+ * The {@link JseBaseLib} implements {@link FINDER} by scanning the current directory
- * @see org.luaj.vm2.lib.jse.JseBaseLib
+ * first, then falling back to   {@link Class#getResource(String)} if that fails.
+ * Otherwise, the behavior is the same as that of {@link BaseLib}.  
+ * <p>  
+ * Typically, this library is included as part of a call to 
+ * {@link JsePlatform#standardGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new JseBaseLib());
+ * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * } </pre>
+ * Doing so will ensure the library is properly initialized 
+ * and loaded into the globals table. 
+ * <p>
+ * This is a direct port of the corresponding library in C.
+ * @see BaseLib
+ * @see ResourceFinder
+ * @see #FINDER
+ * @see LibFunction
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.1">http://www.lua.org/manual/5.1/manual.html#5.1</a>
  */
+
 public class JseBaseLib extends org.luaj.vm2.lib.BaseLib {
 
 	/** Construct a JSE base library instance */

src/jse/org/luaj/vm2/lib/jse/JseIoLib.java

@@ -30,12 +30,40 @@ import java.io.RandomAccessFile;
 
 import org.luaj.vm2.LuaError;
 import org.luaj.vm2.LuaString;
+import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.lib.BaseLib;
 import org.luaj.vm2.lib.IoLib;
+import org.luaj.vm2.lib.LibFunction;
 
 /** 
- * Implementation of the lua io library for J2se using RandomAccessFile
+ * Subclass of {@link IoLib} and therefore {@link LibFunction} which implements the lua standard {@code io} 
- * to implement seek.   
+ * library for the JSE platform. 
+ * <p> 
+ * It uses RandomAccessFile to implement seek on files.  
+ * <p>
+ * Typically, this library is included as part of a call to 
+ * {@link JsePlatform#standardGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new JseBaseLib());
+ * _G.load(new PackageLib());
+ * _G.load(new JseIoLib());
+ * _G.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
+ * } </pre>
+ * Doing so will ensure the library is properly initialized 
+ * and loaded into the globals table. 
+ * <p>
+ * This has been implemented to match as closely as possible the behavior in the corresponding library in C.
+ * @see LibFunction
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see IoLib
+ * @see JmeIoLib
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.7">http://www.lua.org/manual/5.1/manual.html#5.7</a>
  */
 public class JseIoLib extends IoLib {
 

src/jse/org/luaj/vm2/lib/jse/JseMathLib.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
@@ -22,15 +22,39 @@
 package org.luaj.vm2.lib.jse;
 
 import org.luaj.vm2.LuaValue;
-import org.luaj.vm2.lib.MathLib;
+import org.luaj.vm2.lib.LibFunction;
 import org.luaj.vm2.lib.OneArgFunction;
 import org.luaj.vm2.lib.TwoArgFunction;
 
 /** 
- * Math library implementation for use on JSE platform.
+ * Subclass of {@link LibFunction} which implements the lua standard {@code math} 
- * 
+ * library. 
- * Implements all "math" functions, including platform-specific
+ * <p> 
- * overrides for pow() and exp()
+ * It contains all lua math functions, including those not available on the JME platform.  
+ * See {@link org.luaj.lib.MathLib} for the exception list.  
+ * <p>
+ * Typically, this library is included as part of a call to 
+ * {@link JsePlatform#standardGlobals()} 
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new JseBaseLib());
+ * _G.load(new PackageLib());
+ * _G.load(new JseMathLib());
+ * System.out.println( _G.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
+ * } </pre>
+ * Doing so will ensure the library is properly initialized 
+ * and loaded into the globals table. 
+ * <p>
+ * This has been implemented to match as closely as possible the behavior in the corresponding library in C.
+ * @see LibFunction
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see JseMathLib
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.6">http://www.lua.org/manual/5.1/manual.html#5.6</a>
  */
 public class JseMathLib extends org.luaj.vm2.lib.MathLib {
 	

src/jse/org/luaj/vm2/lib/jse/JseOsLib.java

@@ -23,18 +23,46 @@ package org.luaj.vm2.lib.jse;
 import java.io.File;
 import java.io.IOException;
 
+import org.luaj.vm2.LuaValue;
+import org.luaj.vm2.lib.LibFunction;
+
 /**
- * Implementation of the lua os library for J2se.
+ * Subclass of {@link LibFunction} which implements the standard lua {@code os} library.
- * 
+ * <p>
- * <p>Implements features specific to the J2se environment:
+ * This contains more complete implementations of the following functions 
- * <bl>
+ * using features that are specific to JSE:   
- * <li>execute()</li>
+ * <ul>
- * <li>remove()</li>
+ * <li>{@code execute()}</li>
- * <li>rename()</li>
+ * <li>{@code remove()}</li>
- * <li>tmpname()</li>
+ * <li>{@code rename()}</li>
- * </bl>
+ * <li>{@code tmpname()}</li>
- * 
+ * </ul>
- * @see org.luaj.vm2.lib.OsLib
+ * <p>
+ * Because the nature of the {@code os} library is to encapsulate 
+ * os-specific features, the behavior of these functions varies considerably 
+ * from their counterparts in the C platform.  
+ * <p>
+ * Typically, this library is included as part of a call to either 
+ * {@link JsePlatform#standardGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new JseBaseLib());
+ * _G.load(new PackageLib());
+ * _G.load(new JseOsLib());
+ * System.out.println( _G.get("os").get("time").call() );
+ * } </pre>
+ * Doing so will ensure the library is properly initialized 
+ * and loaded into the globals table. 
+ * <p>
+ * @see LibFunction
+ * @see OsLib
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.8">http://www.lua.org/manual/5.1/manual.html#5.8</a>
  */
 public class JseOsLib extends org.luaj.vm2.lib.OsLib {
 	

src/jse/org/luaj/vm2/lib/jse/JsePlatform.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2009 Luaj.org. All rights reserved.
+ * Copyright (c) 2009-2011 Luaj.org. All rights reserved.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -24,18 +24,66 @@ package org.luaj.vm2.lib.jse;
 import org.luaj.vm2.compiler.LuaC;
 import org.luaj.vm2.LuaTable;
 import org.luaj.vm2.LuaThread;
+import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.lib.CoroutineLib;
 import org.luaj.vm2.lib.DebugLib;
 import org.luaj.vm2.lib.PackageLib;
 import org.luaj.vm2.lib.StringLib;
 import org.luaj.vm2.lib.TableLib;
 
+/** The {@link JsePlatform} class is a convenience class to standardize 
+ * how globals tables are initialized for the JSE platform. 
+ * <p>
+ * It is used to allocate either a set of standard globals using 
+ * {@link #standardGlobals()} or debug globals using {@link #debugGlobals()}
+ * <p>
+ * A simple example of initializing globals and using them from Java is:
+ * <pre> {@code
+ * LuaValue _G = JsePlatform.standardGlobals();
+ * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * } </pre>
+ * <p>
+ * Once globals are created, a simple way to load and run a script is:
+ * <pre> {@code
+ * LoadState.load( new FileInputStream("main.lua"), "main.lua", _G ).call();
+ * } </pre>
+ * <p>
+ * although {@code require} could also be used: 
+ * <pre> {@code
+ * _G.get("require").call(LuaValue.valueOf("main"));
+ * } </pre>
+ * For this to succeed, the file "main.lua" must be in the current directory or a resource.
+ * See {@link JseBaseLib} for details on finding scripts using {@link ResourceFinder}.
+ * <p>
+ * The standard globals will contain all standard libraries plus {@code luajava}:
+ * <ul>
+ * <li>{@link JseBaseLib}</li>
+ * <li>{@link PackageLib}</li>
+ * <li>{@link TableLib}</li>
+ * <li>{@link StringLib}</li>
+ * <li>{@link CoroutineLib}</li>
+ * <li>{@link JseMathLib}</li>
+ * <li>{@link JseIoLib}</li>
+ * <li>{@link JseOsLib}</li>
+ * <li>{@link LuajavaLib}</li>
+ * </ul>
+ * In addition, the {@link LuaC} compiler is installed so lua files may be loaded in their source form. 
+ * <p> 
+ * The debug globals are simply the standard globals plus the {@code debug} library {@link DebugLib}.
+ * <p>
+ * The class ensures that initialization is done in the correct order, 
+ * and that linkage is made  to {@link LuaThread#setGlobals(LuaValue)}. 
+ * @see JmePlatform
+ */
 public class JsePlatform {
 
 	/**
 	 * Create a standard set of globals for JSE including all the libraries.
 	 * 
 	 * @return Table of globals initialized with the standard JSE libraries
+	 * @see #debugGlobals()
+	 * @see JsePlatform
+	 * @see JmePlatform
 	 */
 	public static LuaTable standardGlobals() {
 		LuaTable _G = new LuaTable();
@@ -53,6 +101,14 @@ public class JsePlatform {
 		return _G;		
 	}
 
+	/** Create standard globals including the {@link debug} library.
+	 * 
+	 * @return Table of globals initialized with the standard JSE and debug libraries
+	 * @see #standardGlobals()
+	 * @see JsePlatform
+	 * @see JmePlatform
+	 * @see DebugLib
+	 */
 	public static LuaTable debugGlobals() {
 		LuaTable _G = standardGlobals();
 		_G.load(new DebugLib());

src/jse/org/luaj/vm2/lib/jse/LuajavaLib.java

@@ -22,10 +22,6 @@
 package org.luaj.vm2.lib.jse;
 
 
-/** LuaJava-like bindings to Java scripting. 
- * 
- * TODO: coerce types on way in and out, pick method base on arg count ant types.
- */
 import java.lang.reflect.Array;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.Field;
@@ -43,11 +39,48 @@ import org.luaj.vm2.LuaTable;
 import org.luaj.vm2.LuaUserdata;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
+import org.luaj.vm2.compiler.LuaC;
+import org.luaj.vm2.lib.LibFunction;
 import org.luaj.vm2.lib.PackageLib;
 import org.luaj.vm2.lib.ThreeArgFunction;
 import org.luaj.vm2.lib.TwoArgFunction;
 import org.luaj.vm2.lib.VarArgFunction;
 
+/** 
+ * Subclass of {@link LibFunction} which implements the features of the luajava package. 
+ * <p> 
+ * Luajava is an approach to mixing lua and java using simple functions that bind 
+ * java classes and methods to lua dynamically.  The API is documented on the 
+ * <a href="http://www.keplerproject.org/luajava/">luajava</a> documentation pages.
+ * <p>
+ * Typically, this library is included as part of a call to either 
+ * {@link JsePlatform#standardGlobals()}
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * LuaC.install();
+ * _G.load(new BaseLib());
+ * _G.load(new PackageLib());
+ * _G.load(new LuajavaLib());
+ * _G.get("loadstring").call( LuaValue.valueOf( 
+ * 		"sys = luajava.bindClass('java.lang.System')\n"+
+ * 		"print ( sys:currentTimeMillis() )\n" ) ).call(); 
+ * } </pre>
+ * This example is not intended to be realistic - only to show how the {@link LuajavaLib} 
+ * may be initialized by hand.  In practice, the {@code luajava} library is available 
+ * on all JSE platforms via the call to {@link JsePlatform#standardGlobals()}
+ * and the luajava api's are simply invoked from lua.    
+ * <p>
+ * This has been implemented to match as closely as possible the behavior in the corresponding library in C.
+ * @see LibFunction
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see LuaC
+ * @see <a href="http://www.keplerproject.org/luajava/manual.html#luareference">http://www.keplerproject.org/luajava/manual.html#luareference</a>
+ */
 public class LuajavaLib extends VarArgFunction {
 	
 	static final int INIT           = 0;

src/jse/org/luaj/vm2/luajc/LuaJC.java

@@ -32,6 +32,30 @@ import org.luaj.vm2.Prototype;
 import org.luaj.vm2.LoadState.LuaCompiler;
 import org.luaj.vm2.compiler.LuaC;
 
+/**
+ * Implementation of {@link LuaCompiler} which does direct 
+ * lua-to-java-bytecode compiling. 
+ * <p>
+ * This requires the bcel library to be on the class path to work as expected.  
+ * If the library is not found, the default {@link LuaC} lua-to-lua-bytecode 
+ * compiler will be used.  
+ * <p>
+ * The compiler should be installed as part of globals initialization, 
+ * and before any scripts or lua code is executed. 
+ * A typical example is to install it following the globals creation, 
+ * as in the following:
+ * <pre> {@code
+ * LuaValue _G = JsePlatform.standardGlobals();
+ * LuaJC.install();
+ * LoadState.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
+ * } </pre>
+ * @see LuaCompiler
+ * @see LuaC
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see BaseLib
+ * @see LuaValue
+ */
 public class LuaJC implements LuaCompiler {
 
 	private static final String NON_IDENTIFIER = "[^a-zA-Z0-9_$/.\\-]";