From c49ede53e47eef5ea20b14c0bf546453d05cb23f Mon Sep 17 00:00:00 2001 From: James Roseborough Date: Wed, 26 Jan 2011 06:02:06 +0000 Subject: [PATCH] Tune javadoc for distribution build. --- build.xml | 17 ++++--- src/core/org/luaj/vm2/LuaValue.java | 19 ++++---- .../org/luaj/vm2/lib/jse/CoerceJavaToLua.java | 44 ++++++++++++++++++- .../org/luaj/vm2/lib/jse/CoerceLuaToJava.java | 24 +++++++++- 4 files changed, 87 insertions(+), 17 deletions(-) diff --git a/build.xml b/build.xml index cc2a7682..d74dad48 100644 --- a/build.xml +++ b/build.xml @@ -5,7 +5,7 @@ - + @@ -132,7 +132,8 @@ - + + @@ -140,14 +141,15 @@ - + + + Luaj API]]> Copyright © 2007-2008 Luaj.org. All Rights Reserved.]]> @@ -157,7 +159,7 @@ - + @@ -193,6 +195,9 @@ + + + diff --git a/src/core/org/luaj/vm2/LuaValue.java b/src/core/org/luaj/vm2/LuaValue.java index 9ddb3084..de3cbbd7 100644 --- a/src/core/org/luaj/vm2/LuaValue.java +++ b/src/core/org/luaj/vm2/LuaValue.java @@ -1325,17 +1325,18 @@ public class LuaValue extends Varargs { *

* To iterate over integer keys in a table you can use * 

 {@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 )
-	 * }
+ * 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 ) + * } + * } * @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 diff --git a/src/jse/org/luaj/vm2/lib/jse/CoerceJavaToLua.java b/src/jse/org/luaj/vm2/lib/jse/CoerceJavaToLua.java index 75be82fa..6b5e58df 100644 --- a/src/jse/org/luaj/vm2/lib/jse/CoerceJavaToLua.java +++ b/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. + *

+ * This class is primarily used by the {@link LuajavaLib}, + * but can also be used directly when working with Java/lua bindings. + *

+ * To coerce scalar types, the various, generally the {@code valueOf(type)} methods + * on {@link LuaValue} may be used: + *

    + *
  • {@link LuaValue#valueOf(boolean)}
    • + *
  • {@link LuaValue#valueOf(byte[])}
    • + *
  • {@link LuaValue#valueOf(double)}
    • + *
  • {@link LuaValue#valueOf(int)}
    • + *
  • {@link LuaValue#valueOf(String)}
    • + *
+ *

+ * To coerce arrays of objects and lists, the {@code listOf(..)} and {@code tableOf(...)} methods + * on {@link LuaValue} may be used: + *

    + *
  • {@link LuaValue#listOf(LuaValue[])}
    • + *
  • {@link LuaValue#listOf(LuaValue[], org.luaj.vm2.Varargs)}
    • + *
  • {@link LuaValue#tableOf(LuaValue[])}
    • + *
  • {@link LuaValue#tableOf(LuaValue[], LuaValue[], org.luaj.vm2.Varargs)}
    • + *
+ * 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. + *

+ * 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; diff --git a/src/jse/org/luaj/vm2/lib/jse/CoerceLuaToJava.java b/src/jse/org/luaj/vm2/lib/jse/CoerceLuaToJava.java index cea1ab29..e759c534 100644 --- a/src/jse/org/luaj/vm2/lib/jse/CoerceLuaToJava.java +++ b/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. + *

+ * This class is primarily used by the {@link LuajavaLib}, + * but can also be used directly when working with Java/lua bindings. + *

+ * To coerce to specific Java values, generally the {@code toType()} methods + * on {@link LuaValue} may be used: + *

    + *
  • {@link LuaValue#toboolean()}
    • + *
  • {@link LuaValue#tobyte()}
    • + *
  • {@link LuaValue#tochar()}
    • + *
  • {@link LuaValue#toshort()}
    • + *
  • {@link LuaValue#toint()}
    • + *
  • {@link LuaValue#tofloat()}
    • + *
  • {@link LuaValue#todouble()}
    • + *
  • {@link LuaValue#tojstring()}
    • + *
  • {@link LuaValue#touserdata()}
    • + *
  • {@link LuaValue#touserdata(Class)}
    • + *
+ *

+ * 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 ); };