more dok

1 files changed, 90 insertions, 4 deletions

diff --git a/dok/index.dok b/dok/index.dok
index 422c606..62a71ba 100644
--- a/dok/index.dok
+++ b/dok/index.dok
@@ -18,7 +18,7 @@ int numel(THDoubleTensor *t);
 which returns the number of elements of ''t''.
 Writing a complete wrapper of this function would look like:
 <file c>
-int wrapper_numel(lua_State *L)
+static int wrapper_numel(lua_State *L)
 {
   THDoubleTensor *t;
 
@@ -52,7 +52,6 @@ sometimes it is also good to do everything by hand yourself!
 
 **wrap** provides only one class: ''CInterface''. Considering our easy example, a typical usage
 would be:
-'
 <file lua>
 require 'wrap'
 
@@ -61,7 +60,8 @@ interface = wrap.CInterface.new()
 interface:wrap(
    "numel", -- the Lua name
    "numel", -- the C function name, here the same
-   -- now we describe the 'arguments' (or possibly returned values)
+   -- now we describe the 'arguments' of the C function
+   -- (or possible returned values)
    {
       {name="DoubleTensor"},
       {name="int", creturned=true} -- this one is returned by the C function
@@ -70,7 +70,10 @@ interface:wrap(
 
 print(interface:tostring())
 </file>
-The wrapper generated by **wrap** is quite similar to what one would write by hand:
+''CInterface'' contains only few methods. [[#CInterface.wrap|wrap()]] is
+the most important one. [[#CInterface.tostring|tostring()]] returns a
+string containing all the code produced until now.  The wrapper generated
+by **wrap** is quite similar to what one would write by hand:
 <file c>
 static int wrapper_numel(lua_State *L)
 {
@@ -89,3 +92,86 @@ static int wrapper_numel(lua_State *L)
   return 1;
 }
 </file>
+
+We know describe the few methods provided by ''CInterface''.
+
+==== new() ====
+{{anchor:CInterface.new}}
+
+Returns a new ''CInterface''.
+
+==== print(str) ====
+{{anchor:CInterface.print}}
+
+Add some hand-crafted code to the existing generated code. You might want to do that if your wrapper
+requires manual tweaks. For e.g., in the example above, the "id" related to ''torch.DoubleTensor''
+needs to be defined beforehand:
+<file lua>
+interface:print([[
+const void* torch_DoubleTensor_id;
+]])
+</file>
+
+==== luaname2wrapname(name) ====
+{{anchor:CInterface.luaname2wrapname}}
+
+This method defines the name of each generated wrapping function (like
+''wrapper_numel'' in the example above), given the Lua name of a function
+(say ''numel''). In general, this has little importance, as the wrapper is
+a static function which is not going to be called outside the scope of the
+wrap file. However, if you generate some complex wrappers, you might want
+to have a control on this to avoid name clashes. The default is
+<file lua>
+function CInterface:luaname2wrapname(name)
+   return string.format("wrapper_%s", name)
+end
+</file>
+Changing it to something else can be easily done with (still following the example above)
+<file lua>
+function interface:luaname2wrapname(name)
+   return string.format("my_own_naming_%s", name)
+end
+</file>
+
+==== register(name) ====
+
+Produces C code defining a
+[[http://www.lua.org/manual/5.1/manual.html#luaL_Reg|luaL_Reg]] structure
+(which will have the given ''name''). In the above example, calling
+<file lua>
+interface:register('myfuncs')
+</file>
+will generate the following additional code:
+<file c>
+static const struct luaL_Reg myfuncs [] = {
+  {"numel", wrapper_numel},
+  {NULL, NULL}
+};
+</file>
+
+This structure is meant to be passed as argument to
+[[http://www.lua.org/manual/5.1/manual.html#luaL_register|luaL_register]],
+such that Lua will be aware of your new functions. For e.g., the following
+would declare ''mylib.numel'' in Lua:
+<file lua>
+interface:print([[
+luaL_register(L, "mylib", myfuncs);
+]])
+</file>
+
+==== tostring() ====
+{{anchor:CInterface.tostring}}
+
+Returns a string containing all the code generated by the ''CInterface''
+until now. Note that the history is not erased.
+
+==== tofile(filename) ====
+{{anchor:CInterface.tofile}}
+
+Write in the file (named after ''filename'') all the code generated by the
+''CInterface'' until now. Note that the history is not erased.
+
+==== clearhistory() ====
+{{anchor:CInterface.clearhhistory}}
+
+Forget about all the code generated by the ''CInterface'' until now.