Update javadoc comments related to library inintialization.

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

@@ -35,10 +35,10 @@ import org.luaj.vm2.lib.ResourceFinder;
  * Global environment used by luaj.
  * <p>
  * Contains the global variables referenced by lua libraries such as stdin and stdout, 
- * the resrouce finder which is used tolook up files in a platform independent way, 
+ * the resource finder which is used to look up files in a platform independent way, 
  * the installed lua compiler, the math library in use, debugging calls stack, and so on.  
  * <p>
- * In a multithreded server environment, each server thread should create one Globals instance, 
+ * In a multi-threaded server environment, each server thread should create one Globals instance, 
  * which will be logically distance and not interfere with each other, but share certain 
  * static immutable resources such as class data and string data.
  * <p>
@@ -46,12 +46,12 @@ import org.luaj.vm2.lib.ResourceFinder;
  * {@link JsePlatform.standardGlobasl()} or {@link JmePlatform.standardGlobals()}, 
  * and then used to load lua scripts for execution as in the following example. 
  * <pre> {@code
- * Globals _G = JsePlatform.standardGlobals();
- * _G.compiler.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.compiler.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
  * } </pre>
  * @see LuaCompiler
- * @see JsePlatform
- * @see JmePlatform
+ * @see org.luaj.vm2.lib.jse.JsePlatform
+ * @see org.luaj.vm2.lib.jme.JmePlatform
  * @see LuaValue
  *  
  */
@@ -107,13 +107,16 @@ public class Globals extends LuaTable {
 		return this;
 	}
 	
-	/** The installed loader. */
+	/** The installed loader. 
+	 * @see Loader */
 	public Loader loader;
 
-	/** The installed compiler. */
+	/** The installed compiler.
+	 * @see Compiler */
 	public Compiler compiler;
 
-	/** The installed undumper. */
+	/** The installed undumper.
+	 * @see Undumper */
 	public Undumper undumper;
 
 	/** Convenience function for loading a file that is either binary lua or lua source.

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

@@ -22,7 +22,6 @@
 package org.luaj.vm2.lib;
 
 import org.luaj.vm2.Globals;
-import org.luaj.vm2.LuaError;
 import org.luaj.vm2.LuaTable;
 import org.luaj.vm2.LuaThread;
 import org.luaj.vm2.LuaValue;

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

@@ -30,7 +30,6 @@ 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;
 
@@ -43,27 +42,30 @@ import org.luaj.vm2.lib.LibFunction;
  * <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"));
+ * Globals globals = JmePlatform.standardGlobals();
+ * globals.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>
+ * For special cases where the smallest possible footprint is desired, 
+ * a minimal set of libraries could be loaded
+ * directly via {@link Glboals#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * Globals globals = new Globals();
+ * globals.load(new JmeBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new JmeIoLib());
+ * globals.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
+ * } </pre>
+ * <p>However, other libraries such as <em>MathLib</em> are not loaded in this case.
  * <p>
  * This has been implemented to match as closely as possible the behavior in the corresponding library in C.
  * @see LibFunction
- * @see JsePlatform
+ * @see org.luaj.vm2.lib.jse.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>
+ * @see <a href="http://www.lua.org/manual/5.2/manual.html#6.8">Lua 5.2 I/O Lib Reference</a>
  */
 public class JmeIoLib extends IoLib {
 	

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

@@ -53,18 +53,18 @@ import org.luaj.vm2.lib.TableLib;
  * <p>
  * A simple example of initializing globals and using them from Java is:
  * <pre> {@code
- * Globals _G = JmePlatform.standardGlobals();
- * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * Globals global = JmePlatform.standardGlobals();
+ * global.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();
+ * LoadState.load( getClass().getResourceAsStream("main.lua"), "main.lua", globals ).call();
  * } </pre>
  * <p>
  * although {@code require} could also be used: 
  * <pre> {@code
- * _G.get("require").call(LuaValue.valueOf("main"));
+ * globals.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}.
@@ -103,19 +103,19 @@ public class JmePlatform {
 	 * @see JmePlatform
 	 */
 	public static Globals standardGlobals() {
-		Globals _G = new Globals();
-		_G.load(new BaseLib());
-		_G.load(new PackageLib());
-		_G.load(new Bit32Lib());
-		_G.load(new OsLib());
-		_G.load(new MathLib());
-		_G.load(new TableLib());
-		_G.load(new StringLib());
-		_G.load(new CoroutineLib());
-		_G.load(new JmeIoLib());
-		LoadState.install(_G);
-		LuaC.install(_G);
-		return _G;		
+		Globals globals = new Globals();
+		globals.load(new BaseLib());
+		globals.load(new PackageLib());
+		globals.load(new Bit32Lib());
+		globals.load(new OsLib());
+		globals.load(new MathLib());
+		globals.load(new TableLib());
+		globals.load(new StringLib());
+		globals.load(new CoroutineLib());
+		globals.load(new JmeIoLib());
+		LoadState.install(globals);
+		LuaC.install(globals);
+		return globals;		
 	}
 	
 	/** Create standard globals including the {@link debug} library.
@@ -127,8 +127,8 @@ public class JmePlatform {
 	 * @see DebugLib
 	 */
 	public static Globals debugGlobals() {
-		Globals _G = standardGlobals();
-		_G.load(new DebugLib());
-		return _G;
+		Globals globals = standardGlobals();
+		globals.load(new DebugLib());
+		return globals;
 	}
 }

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

@@ -43,26 +43,30 @@ import org.luaj.vm2.lib.ResourceFinder;
  * <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"));
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.get("print").call(LuaValue.valueOf("hello, world"));
  * } </pre>
- * Doing so will ensure the library is properly initialized 
- * and loaded into the globals table. 
+ * <p>
+ * For special cases where the smallest possible footprint is desired, 
+ * a minimal set of libraries could be loaded
+ * directly via {@link Globals#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.get("print").call(LuaValue.valueOf("hello, world"));
+ * } </pre>
+ * <p>However, other libraries such as <em>PackageLib</em> are not loaded in this case.
  * <p>
  * This is a direct port of the corresponding library in C.
+ * @see Globals
  * @see BaseLib
  * @see ResourceFinder
- * @see #FINDER
+ * @see {@link Globals.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>
+ * @see org.luaj.vm2.lib.jme.JmePlatform
+ * @see <a href="http://www.lua.org/manual/5.2/manual.html#6.1">Lua 5.2 Base Lib Reference</a>
  */
 
 public class JseBaseLib extends org.luaj.vm2.lib.BaseLib {

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

@@ -21,7 +21,6 @@
 ******************************************************************************/
 package org.luaj.vm2.lib.jse;
 
-
 import java.io.BufferedInputStream;
 import java.io.EOFException;
 import java.io.IOException;
@@ -33,7 +32,6 @@ 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;
 
@@ -45,27 +43,30 @@ import org.luaj.vm2.lib.LibFunction;
  * <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"));
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.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>
+ * For special cases where the smallest possible footprint is desired, 
+ * a minimal set of libraries could be loaded
+ * directly via {@link Glboals#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new JseIoLib());
+ * globals.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
+ * } </pre>
+ * <p>However, other libraries such as <em>MathLib</em> are not loaded in this case.
  * <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 org.luaj.vm2.lib.jme.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>
+ * @see <a href="http://www.lua.org/manual/5.2/manual.html#6.8">Lua 5.2 I/O Lib Reference</a>
  */
 public class JseIoLib extends IoLib {
 

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

@@ -32,27 +32,30 @@ import org.luaj.vm2.lib.LibFunction;
  * 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:
+ * {@link JsePlatform#standardGlobals()}
  * <pre> {@code
- * LuaTable _G = new LuaTable();
- * LuaThread.setGlobals(_G);
- * _G.load(new JseBaseLib());
- * _G.load(new PackageLib());
- * _G.load(new JseMathLib());
+ * Globals globals = JsePlatform.standardGlobals();
  * 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>
+ * For special cases where the smallest possible footprint is desired, 
+ * a minimal set of libraries could be loaded
+ * directly via {@link Glboals#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new JseMathLib());
+ * System.out.println( _G.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
+ * } </pre>
+ * <p>However, other libraries such as <em>CoroutineLib</em> are not loaded in this case.
  * <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 org.luaj.vm2.lib.jme.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>
+ * @see <a href="http://www.lua.org/manual/5.2/manual.html#6.6">Lua 5.2 Math Lib Reference</a>
  */
 public class JseMathLib extends org.luaj.vm2.lib.MathLib {
 	

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

@@ -20,6 +20,7 @@
 * THE SOFTWARE.
 ******************************************************************************/
 package org.luaj.vm2.lib.jse;
+
 import java.io.File;
 import java.io.IOException;
 
@@ -43,27 +44,30 @@ import org.luaj.vm2.lib.LibFunction;
  * 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 
+ * 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 JseOsLib());
+ * Globals globals = JsePlatform.standardGlobals();
  * 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>
+ * For special cases where the smallest possible footprint is desired, 
+ * a minimal set of libraries could be loaded
+ * directly via {@link Glboals#load(LuaValue)} using code such as:
+ * <pre> {@code
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new JseOsLib());
+ * System.out.println( _G.get("os").get("time").call() );
+ * } </pre>
+ * <p>However, other libraries such as <em>MathLib</em> are not loaded in this case.
  * <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>
+ * @see org.luaj.vm2.lib.jme.JmePlatform
+ * @see <a href="http://www.lua.org/manual/5.2/manual.html#6.9">Lua 5.2 OS Lib Reference</a>
  */
 public class JseOsLib extends org.luaj.vm2.lib.OsLib {
 	

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

@@ -42,18 +42,18 @@ import org.luaj.vm2.lib.TableLib;
  * <p>
  * A simple example of initializing globals and using them from Java is:
  * <pre> {@code
- * Globals _G = JsePlatform.standardGlobals();
- * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.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
- * _G.load( new FileInputStream("main.lua"), "main.lua" ).call();
+ * globals.load( new FileInputStream("main.lua"), "main.lua" ).call();
  * } </pre>
  * <p>
  * although {@code require} could also be used: 
  * <pre> {@code
- * _G.get("require").call(LuaValue.valueOf("main"));
+ * globals.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}.
@@ -91,20 +91,20 @@ public class JsePlatform {
 	 * @see JmePlatform
 	 */
 	public static Globals standardGlobals() {
-		Globals _G = new Globals();
-		_G.load(new JseBaseLib());
-		_G.load(new PackageLib());
-		_G.load(new Bit32Lib());
-		_G.load(new TableLib());
-		_G.load(new StringLib());
-		_G.load(new CoroutineLib());
-		_G.load(new JseMathLib());
-		_G.load(new JseIoLib());
-		_G.load(new JseOsLib());
-		_G.load(new LuajavaLib());
-		LoadState.install(_G);
-		LuaC.install(_G);
-		return _G;		
+		Globals globals = new Globals();
+		globals.load(new JseBaseLib());
+		globals.load(new PackageLib());
+		globals.load(new Bit32Lib());
+		globals.load(new TableLib());
+		globals.load(new StringLib());
+		globals.load(new CoroutineLib());
+		globals.load(new JseMathLib());
+		globals.load(new JseIoLib());
+		globals.load(new JseOsLib());
+		globals.load(new LuajavaLib());
+		LoadState.install(globals);
+		LuaC.install(globals);
+		return globals;		
 	}
 
 	/** Create standard globals including the {@link debug} library.
@@ -116,9 +116,9 @@ public class JsePlatform {
 	 * @see DebugLib
 	 */
 	public static Globals debugGlobals() {
-		Globals _G = standardGlobals();
-		_G.load(new DebugLib());
-		return _G;
+		Globals globals = standardGlobals();
+		globals.load(new DebugLib());
+		return globals;
 	}