Lua: document rocklib_aux.pl a bit, so it's easier to find out about it when stumbling over a CC error in rocklib_aux.c

git-svn-id: svn://svn.rockbox.org/rockbox/trunk@26912 a1c6a512-1295-4272-9138-f99709370657

2 files changed, 18 insertions, 1 deletions

diff --git a/apps/plugins/lua/rocklib.c b/apps/plugins/lua/rocklib.c
index 73c3851bc1..46572014f0 100644
--- a/apps/plugins/lua/rocklib.c
+++ b/apps/plugins/lua/rocklib.c
@@ -38,6 +38,10 @@
  * a C function just pushes them onto the stack, in direct order (the first result is pushed first),
  * and returns the number of results. Any other value in the stack below the results will be properly
  * discarded by Lua. Like a Lua function, a C function called by Lua can also return many results. 
+ *
+ * When porting new functions, don't forget to check rocklib_aux.pl whether it automatically creates
+ * wrappers for the function and if so, add the function names to @forbidden_functions. This is to
+ * prevent namespace collisions and adding duplicate wrappers.
  */
 
 
diff --git a/apps/plugins/lua/rocklib_aux.pl b/apps/plugins/lua/rocklib_aux.pl
index b63aaee18a..77fd08b119 100755
--- a/apps/plugins/lua/rocklib_aux.pl
+++ b/apps/plugins/lua/rocklib_aux.pl
@@ -18,6 +18,13 @@
 #
 ############################################################################
 
+
+# The purpose of this script is to automatically generate Lua wrappers for
+# (easily) portable C functions used in the Rockbox plugin API.
+# It doesn't contain support for enums, structs or pointers (apart from char*).
+#
+# The output will be written to <build_dir>/apps/plugins/lua/rocklib_aux.c
+
 sub trim
 {
     my $text = $_[0];
@@ -40,6 +47,9 @@ sub rand_string
 
 my @functions;
 my @ported_functions;
+# These functions are excluded from automatically wrapping. This is useful if
+# you want to manually port them to Lua. The format is a standard Perl regular
+# expression.
 my @forbidden_functions = ('^open$',
                            '^close$',
                            '^read$',
@@ -111,7 +121,10 @@ my $svnrev = '$Revision$';
 
 # Print the header
 print <<EOF
-/* Automatically generated of $svnrev from rocklib.c & plugin.h */
+/* Automatically generated from rocklib.c & plugin.h ($svnrev)
+ *
+ * See apps/plugins/lua/rocklib_aux.pl for the generator.
+ */
 
 #define lrocklib_c
 #define LUA_LIB