Tune javadoc for distribution build.

build.xml

@@ -5,7 +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"/>
+	<property name="jar.name.sources" value="luaj-sources-${version}.jar"/>
 
 	<import file="wtk.xml"/>
 
@@ -132,7 +132,8 @@
 	</target>
 
 	<target name="jar-jse-sources" depends="compile">
-		<jar destfile="${jar.name.jse.sources}">
+		<jar destfile="${jar.name.sources}">
+		    <fileset dir="build/jme/src"/>
 		    <fileset dir="build/jse/src"/>
 		</jar>
 	</target>
@@ -140,14 +141,15 @@
 	<target name="doc">
 		<delete dir="docs/api"/>
 		<mkdir dir="docs/api"/>
-		<javadoc packagenames="org.luaj.vm2.*"
-				sourcepath="src/core"
-				defaultexcludes="yes"
+		<javadoc defaultexcludes="yes"
 				destdir="docs/api"
 				author="true"
 				version="true"
 				use="true"
 				windowtitle="Luaj API">
+		    <fileset dir="src/core" defaultexcludes="yes" includes="org/luaj/vm2/*.java,org/luaj/vm2/compiler/LuaC.java,org/luaj/vm2/lib/*.java"/>
+		    <fileset dir="src/jse" defaultexcludes="yes" includes="org/luaj/vm2/lib/jse/*.java,org/luaj/vm2/luajc/LuaJC.java"/>
+		    <fileset dir="src/jme" defaultexcludes="yes" includes="org/luaj/vm2/lib/jme/*.java"/>
 			<doctitle><![CDATA[<h1>Luaj API</h1>]]></doctitle>
 			<bottom><![CDATA[<i>Copyright &#169; 2007-2008 Luaj.org. All Rights Reserved.</i>]]></bottom>
 			<tag name="todo" scope="all" description="To do:"/>
@@ -157,7 +159,7 @@
 		</javadoc>
 	</target>
 	
-	<target name="dist" depends="all">
+	<target name="dist" depends="all,doc">
 		<delete dir="build/luaj-${version}"/>
 		<mkdir dir="build/luaj-${version}/src"/>
 		<mkdir dir="build/luaj-${version}/lib"/>
@@ -193,6 +195,9 @@
 				<include name=".project"/>
 		    </fileset>		
 		</copy>
+		<copy todir="build/luaj-${version}/docs">
+			<fileset dir="docs"/>
+		</copy>
 		<zip destfile="luaj-${version}.zip" 
 			basedir="build" includes="luaj-${version}/**"/>
 	</target>

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

@@ -1325,17 +1325,18 @@ public class LuaValue extends Varargs {
 	 * <p>
 	 * To iterate over integer keys in a table you can use
 	 * <pre> {@code
-	 * LuaValue k = LuaValue.NIL;
-	 * while ( true ) {
-	 *    Varargs n = table.inext(k);
-	 *    if ( (k = n.arg1()).isnil() )
-	 *       break;
-	 *    LuaValue v = n.arg(2)
-	 *    process( k, v )
-	 * }</pre>
+	 *   LuaValue k = LuaValue.NIL;
+	 *   while ( true ) {
+	 *      Varargs n = table.inext(k);
+	 *      if ( (k = n.arg1()).isnil() )
+	 *         break;
+	 *      LuaValue v = n.arg(2)
+	 *      process( k, v )
+	 *   }
+	 * } </pre>
 	 * @param index {@link LuaInteger} value identifying a key to start from, 
 	 * or {@link NIL} to start at the beginning
-	 * @return {@link Varargs} containing {key,value} for the next entry, 
+	 * @return {@link Varargs} containing {@code (key,value)} for the next entry, 
 	 * or {@link NONE} if there are no more.
 	 * @throws LuaError if {@code this} is not a table, or the supplied key is invalid.
 	 * @see LuaTable

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

@@ -31,12 +31,38 @@ import org.luaj.vm2.LuaValue;
 
 /**
  * Helper class to coerce values from Java to lua within the luajava library. 
+ * <p>
+ * This class is primarily used by the {@link LuajavaLib}, 
+ * but can also be used directly when working with Java/lua bindings. 
+ * <p>
+ * To coerce scalar types, the various, generally the {@code valueOf(type)} methods 
+ * on {@link LuaValue} may be used:
+ * <ul>
+ * <li>{@link LuaValue#valueOf(boolean)}</li>
+ * <li>{@link LuaValue#valueOf(byte[])}</li>
+ * <li>{@link LuaValue#valueOf(double)}</li>
+ * <li>{@link LuaValue#valueOf(int)}</li>
+ * <li>{@link LuaValue#valueOf(String)}</li>
+ * </ul>
+ * <p>
+ * To coerce arrays of objects and lists, the {@code listOf(..)} and {@code tableOf(...)} methods 
+ * on {@link LuaValue} may be used:
+ * <ul>
+ * <li>{@link LuaValue#listOf(LuaValue[])}</li>
+ * <li>{@link LuaValue#listOf(LuaValue[], org.luaj.vm2.Varargs)}</li>
+ * <li>{@link LuaValue#tableOf(LuaValue[])}</li>
+ * <li>{@link LuaValue#tableOf(LuaValue[], LuaValue[], org.luaj.vm2.Varargs)}</li>
+ * </ul>
+ * The method {@link CoerceJavaToLua#coerce(Object)} looks as the type and dimesioning 
+ * of the argument and tries to guess the best fit for corrsponding lua scalar, 
+ * table, or table of tables. 
  * 
+ * @see CoerceJavaToLua#coerce(Object)
  * @see LuajavaLib
  */
 public class CoerceJavaToLua {
 	
-	public static interface Coercion { 
+	static interface Coercion { 
 		public LuaValue coerce( Object javaValue );
 	};
 	
@@ -82,6 +108,22 @@ public class CoerceJavaToLua {
 		COERCIONS.put( String.class, stringCoercion );
 	}
 
+	/**
+	 * Coerse a Java object to a corresponding lua value. 
+	 * <p>
+	 * Integral types {@code boolean}, {@code byte},  {@code char}, and {@code int} 
+	 * will become {@link LuaInteger};
+	 * {@code long}, {@code float}, and {@code double} will become {@link LuaDouble};
+	 * {@code String} and {@code byte[]} will become {@link LuaString}; 
+	 * other types will become {@link LuaUserdata}.
+	 * @param o Java object needing conversion
+	 * @return {@link LuaValue} corresponding to the supplied Java value. 
+	 * @see LuaValue
+	 * @see LuaInteger
+	 * @see LuaDouble
+	 * @see LuaString
+	 * @see LuaUserdata
+	 */
 	public static LuaValue coerce(Object o) {
 		if ( o == null )
 			return LuaValue.NIL;

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

@@ -31,12 +31,34 @@ import org.luaj.vm2.Varargs;
 
 /**
  * Helper class to coerce values from lua to Java within the luajava library. 
+ * <p>
+ * This class is primarily used by the {@link LuajavaLib}, 
+ * but can also be used directly when working with Java/lua bindings. 
+ * <p>
+ * To coerce to specific Java values, generally the {@code toType()} methods 
+ * on {@link LuaValue} may be used:
+ * <ul>
+ * <li>{@link LuaValue#toboolean()}</li>
+ * <li>{@link LuaValue#tobyte()}</li>
+ * <li>{@link LuaValue#tochar()}</li>
+ * <li>{@link LuaValue#toshort()}</li>
+ * <li>{@link LuaValue#toint()}</li>
+ * <li>{@link LuaValue#tofloat()}</li>
+ * <li>{@link LuaValue#todouble()}</li>
+ * <li>{@link LuaValue#tojstring()}</li>
+ * <li>{@link LuaValue#touserdata()}</li>
+ * <li>{@link LuaValue#touserdata(Class)}</li>
+ * </ul>
+ * <p>
+ * For data in lua tables, the various methods on {@link LuaTable} can be used directly 
+ * to convert data to something more useful.
  * 
  * @see LuajavaLib
+ * @see CoerceJavaToLua
  */
 public class CoerceLuaToJava {
 
-	public static interface Coercion { 
+	static interface Coercion { 
 		public Object coerce( LuaValue value );
 		public int score( int paramType );
 	};