more dok

1 files changed, 110 insertions, 1 deletions

diff --git a/dok/index.dok b/dok/index.dok
index 62a71ba..fa0868f 100644
--- a/dok/index.dok
+++ b/dok/index.dok
@@ -93,13 +93,68 @@ static int wrapper_numel(lua_State *L)
 }
 </file>
 
-We know describe the few methods provided by ''CInterface''.
+We know describe the methods provided by ''CInterface''.
 
 ==== new() ====
 {{anchor:CInterface.new}}
 
 Returns a new ''CInterface''.
 
+==== wrap(luaname, cfunction, arguments, ...) ====
+{{anchor:CInterface.wrap}}
+
+Tells the ''CInterface'' to generate a wrapper around the C function
+''cfunction''. The function will be called from Lua under the name
+''luaname''. The Lua //list// ''arguments'' must also be provided. It
+describes //all// the arguments of the C function ''cfunction''.
+Optionally, if the C function returns a value and one would like to return
+it in Lua, this additional value can be also described in the argument
+list.
+<file lua>
+   {
+      {name="DoubleTensor"},
+      {name="int", creturned=true} -- this one is returned by the C function
+   }
+</file>
+
+Each argument is described also as a list. The list must at least contain
+the field ''name'', which tells to ''CInterface'' what type of argument you
+want to define. In the above example,
+<file lua>
+{name="DoubleTensor"}
+</file>
+indicates to ''CInterface'' that the first argument of ''numel()'' is of type ''DoubleTensor''.
+
+Arguments are defined into a table ''CInterface.argtypes'', defined at the
+creation of the interface.  Given a ''typename'', the corresponding field
+in ''interface.argtypes[typename]'' must exist, such that ''CInterface''
+knows how to handle the specified argument. A lot of types are already
+created by default, but the user can define more if needed, by filling
+properly the ''argtypes'' table. See the section [[#CInterface.argtypes]]
+for more details about defined types, and how to define additional ones.
+
+Apart the field ''name'', each list describing an argument can contain several optional fields:
+
+''default'': this means the argument will optional in Lua, and the argument will be initialized
+with the given default value if not present in the Lua function call. The ''default'' value might
+have different meanings, depending on the argument type (see [[#CInterface.argtypes]] for more details).
+
+''invisible'': the argument will invisible //from Lua//. This special option requires ''default'' to be set,
+such that ''CInterface'' knows by what initialize this invisible argument.
+
+''returned'': if set to ''true'', the argument will be returned by the Lua function. Note that several
+values might be returned at the same time in Lua.
+
+''creturned'': if ''true'', tells to ''CInterface'' that this 'argument' is
+in fact the value returned by the C function.  This 'argument' cannot have
+a ''default'' value. Also, as in C one can return only one value, only one
+'argument' can contain this field! Mixing arguments which are ''returned''
+and arguments which are ''creturned'' with ''CInterface'' is not
+recommended: use with care.
+
+While these optional fields are generic to any argument types, some types might define additional optional fields.
+Again, see [[#CInterface.argtypes]] for more details.
+
 ==== print(str) ====
 {{anchor:CInterface.print}}
 
@@ -175,3 +230,57 @@ Write in the file (named after ''filename'') all the code generated by the
 {{anchor:CInterface.clearhhistory}}
 
 Forget about all the code generated by the ''CInterface'' until now.
+
+===== Argument Types =====
+{{anchor:CInterface.argtypes}}
+
+Any ''CInterface'' is initialized with a default ''argtypes'' list, at
+creation. This list tells to ''CInterface'' how to handle type names given to
+the [[#CInterface.wrap|wrap()]] method. The user can add more types to this list, if wanted.
+
+arg.i
+arg.__metatable
+arg.args
+
+==== Standard C types ====
+Standard type names include ''unsigned char'', ''char'', ''short'',
+''int'', ''long'', ''float'' and ''double''. They define the corresponding
+C types, which are converted to/from
+[[http://www.lua.org/manual/5.1/manual.html#lua_Number|lua_Number]].
+
+Additionaly, ''byte'' is an equivalent naming for ''unsigned char'', and
+''boolean'' is interpreted as a boolean in Lua, and an int in C.
+
+''real'' will also be converted to/from a ''lua_Number'', while assuming that
+it is defined in C as ''float'' or ''double''.
+
+Finally, ''index'' defines a long C value, which is going to be
+automatically incremented by 1 when going from C to Lua, and decremented by
+1, when going from Lua to C. This matches Lua policy of having table
+indices starting at 1, and C array indices starting at 0.
+
+For all these number values, the ''default'' field (when defining the
+argument in [[#CInterface.wrap|wrap()]]) can take two types: either a
+number or a function (taking the argument table as argument, and returning a string).
+
+Note that in case of an ''index'' type, the given default value (or result
+given by the default initialization function) will be decremented by 1 when
+initializing the corresponging C ''long'' variable.
+
+Here is an example of defining arguments with a default value:
+<file lua>
+{name="int", default=0}
+</file>
+defines an optional argument which will of type ''int'' in C (lua_Number in Lua), and will take
+the value ''0'' if it is not present when calling the Lua function. A more complicated (but typical) example
+would be:
+<file lua>
+{name="int", default=function(arg)
+                       return string.format("%s", arg.args[1]:carg())
+                     end}
+</file>
+In this case, the argument will be set to the value of the first argument in the Lua function call, if not
+present at call time.
+
+==== Torch Tensor types ====
+