More explanation on an example

Author: bobot

tests/convert/README.md

@@ -0,0 +1,56 @@
+# Example of Conversion
+
+## Files
+    - [`lib.h`](lib.h) from the library to bind
+    - [`generator/generator.ml`](generator/generator.ml) written by the user, describe the stub function and type to generate
+    - [`mylib_stub.h`](mylib_stub.h) generated by camlid from `generator/generator.ml`, contains the definition of the generated type. Includes `lib.h`.
+    - [`mylib_stub.c`](mylib_stub.c) generated by camlid from `generator/generator.ml`, contains the definition of the generated function stub. Includes `mylib_stub.h` and `defs.h`.
+    - [`defs.h`](defs.h) written by the user. Includes `mylib_stub.h`.
+
+## Explanation
+    In this example a C function return some data in an argument if its return
+status is true. So the result of the corresponding function is an algebraic type:
+
+```
+type result = | Data of int | Error of int
+```
+
+This type is generated by camlid with the following corresponding C type and a translation function:
+
+```
+typedef struct {
+  enum { camlid_result_Data, camlid_result_Error} tag;
+  union {
+    struct { intptr_t data; } Data;
+    struct { intptr_t error; } Error;} u; } camlid_result;
+```
+
+Additionally, two C smart-constructors are defined:
+
+```
+// @brief Fill [dst] with the constructor Data of result
+// @param dst structure to fill
+// @param data reference is assigned to the constructor field
+static inline void camlid_mk_result_Data(camlid_result* dst, intptr_t* data)
+
+// @brief Fill [dst] with the constructor Error of result
+// @param dst structure to fill
+// @param error reference is assigned to the constructor field
+static inline void camlid_mk_result_Error(camlid_result* dst,
+intptr_t* error)
+```
+
+So the user only need to define a function that takes the error and the data and fill a `camlid_result`:
+
+```
+static void combine_data_or_status(camlid_result *dst, intptr_t *status, intptr_t *data)
+{
+    if (*status)
+    {
+        camlid_mk_result_Error(dst, status);
+    }
+    else {
+        camlid_mk_result_Data(dst, data);
+    };
+}
+```

tests/convert/generator/generator.ml

@@ -6,9 +6,11 @@ let result =
     [ ("Data", [ ("data", int) ]); ("Error", [ ("error", int) ]) ]
 
 let data, data_or_status =
+  (* data_pc is a variable that will correspond to the C version of the parameter [data] in the stubbed function *)
   let data, data_pc =
     Expert.simple_param ~input:false ~output:false (ptr_ref int) ~name:"data"
   in
+  (* A conversion function takes normally two arguments a pointer to the destination here of type [result] and the source here [int.cty]. For this case we are adding the variable [data_pc] as an additional argument. All the functions that use the C function `combine_data_or_status` have automatically this additional argument added. In the stub function the variable [data_pc] is applied to this additional argument *)
   let ty =
     convert ~c_to_mlc:"combine_data_or_status" ~c:int.cty ~mlc:result
       ~using:[ data_pc ] ()