From d8cef9c0789427a1f5b0cac1a4601a96d9cf1c78 Mon Sep 17 00:00:00 2001
From: Maurus Cuelenaere <mcuelenaere@gmail.com>
Date: Fri, 18 Jun 2010 12:28:34 +0000
Subject: 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
---
 apps/plugins/lua/rocklib.c      |  4 ++++
 apps/plugins/lua/rocklib_aux.pl | 15 ++++++++++++++-
 2 files changed, 18 insertions(+), 1 deletion(-)

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
-- 
cgit v1.2.3