src/ffi: document the differences between the light and full FFI

Signed-off-by: Alexis Laferrière <alexis.laf@xymus.net>

diff --git a/src/ffi/ffi.nit b/src/ffi/ffi.nit
index 15e1dac..e58d32a 100644 (file)
--- a/src/ffi/ffi.nit
+++ b/src/ffi/ffi.nit
@@ -14,9 +14,28 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# FFI concers common between the compilers and the interpreter.
-# Offers services to compile modules using foreign code. Mainly allows
-# to wrap foreign code in Nit methods.
+# Full FFI support, independent of the compiler
+#
+# The full FFI support all the features of the light FFI and more:
+#
+# * More foreign languages: **C++, Java and Objective-C**.
+# * **Callbacks** to Nit from foreign codes.
+#   The callbacks are declared in Nit using the `import` annotation on extern methods.
+#   They are then generated on demand for the target foreign language.
+# * **Static Nit types** in C for precise typing and static typing errors in C.
+# * **Propagating public code blocks** at the module level (C Header).
+#   This allows to use extern classes in foreign code in other modules
+#   without having to import the related headers.
+#   This is optional in C as it is easy to find the correct importation.
+#   However it is important in Java and other complex FFIs.
+# * **Reference pinning** of Nit objects from foreign code.
+#   This ensure that objects referenced from foreign code are not liberated by the GC.
+# * FFI **annotations**:
+#   * `cflags`, `ldflags` and `cppflags` pass arguments to the C and C++
+# compilers and linker.
+#   * `pkgconfig` calls the `pkg-config` program to get the arguments
+# to pass to the C copiler and linker.
+#   * `extra_java_files` adds Java source file to the compilation chain.
 module ffi
 
 import modelbuilder

diff --git a/src/ffi/light_ffi.nit b/src/ffi/light_ffi.nit
index b099681..2245a92 100644 (file)
--- a/src/ffi/light_ffi.nit
+++ b/src/ffi/light_ffi.nit
@@ -14,9 +14,22 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# FFI concers common between the compilers and the interpreter.
-# Offers services to compile modules using foreign code. Mainly allows
-# to wrap foreign code in Nit methods.
+# Light FFI support, independent of the compiler
+#
+# The light FFI offers only basic FFI features:
+#
+# * **Extern methods** implemented in C, nested within the Nit code.
+#   The body of these method is copied directly to the generated C files for compilation.
+#   Also supports extern `new` factories.
+# * Module level **C code blocks**, both "C Body" (the default) and "C Header".
+#   They will be copied to the beginning of the generated C files.
+# * Automatic transformation of Nit **primitive types** from/to their equivalent in C.
+# * **Extern classes** to create a Nit class around a C pointer.
+#   Allows to specify the equivalent C type of the Nit extern class.
+#
+# These limited features should be easy to implement in new/alternative engines
+# to quickly achieve a bootstrap. For this reason, core features of the Nit
+# standard library should be limited to use the light FFI.
 module light_ffi
 
 import modelbuilder