doc: binding-documentation fix review comments
@@ -56,26 +56,31 @@ direct mapping, significantly simplifies the generated code (and maybe also the
### Bindings for the `lowlevel` Library
-If you decide on mapping the functionality of kdb.h 1:1 it is pretty straight-forward.
+Your programming language of choice must provide a way to call into C code (like [cgo](https://golang.org/cmd/cgo/)).
-Your programming language of choice must provide a way to call into C code, e.g.:
-* [cgo](https://golang.org/cmd/cgo/) for the Go programming language
-* [jni](https://docs.oracle.com/javase/8/docs/technotes/guides/jni/) for JAVA
-* [n-api](https://nodejs.org/api/n-api.html) for javascript
+In general we prefer (in this order):
+1. Automatically and statically generated bindings (like [swig](http://www.swig.org/)).
+1. Manually written bindings that directly call to library without any statically build part (like JNI and GI). They are a bit slower but can directly access libelektra.so.
+1. Manually written bindings that are built statically.
-Make sure you have a good understanding of these libraries because some of them can have unexpected downsides.
-CGO for example cannot call variadic C functions because in C the amount of parameters has to be known at compile-time. This is not the case with Go
-since it supports variable length arguments at runtime with the `...` operator.
-
-This is unfortunate because the low-level bindings rely heavily on variadic functions. It is possible to work around this problem by writing helper functions in C that call these variadic functions with a fixed amount of parameters.
+If you want to manually write a binding make sure you have a good understanding of the possible limitations the interop layer can have (e.g. variadic functions).
What you will also need is to set up the Compiler + Linker flags, for this I can recommend [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/), because Elektra already provides `.pc` files.
For garbage collected (GC) languages freeing memory by hand is not something you usually do and since the GC has no knowledge of memory allocated in C we have two options:
* Forcing the user to call the appropriate functions like `keyDel()` themselves, which is very developer unfriendly and error prone or
-* Using language featurse like Java / C++ Destructors or Go's `runtime.SetFinalizer()` function to automatically and reliably release the memory as soon as the native objects are garbage collected
+* Using language featurse like Java / C++ Destructors or Go's `runtime.SetFinalizer()` function to automatically and reliably release the memory as soon as the native objects are garbage collected.
+
+If you decide on mapping the functionality of kdb.h 1:1 it is pretty straight-forward - whereas if you want to adapt or enhance some API's to leverage language features like iterators or operator overloading feel free to do so. The less 'alien' the binding feels to its users the better.
+
+Remember that Elektra has internal iterators (for metadata+keysets) but in general we prefer external iterators by either copying the KeySet per iterator or using `ksAtCursor`.
+
+### Variadic functions
+Some langauges for example cannot call variadic functions because in C the amount of parameters has to be known at compile-time. In Go for example this is not the case since it supports variable length arguments at runtime with the `...` operator.
-If you want to adapt or enhance some API's to leverage language features like iterators or operator overloading feel free to do so. The less 'alien' the binding feels to its users the better.
+This is unfortunate because the low-level bindings rely heavily on variadic functions. It is possible to work around this problem by either
+1. Writing helper functions in C that call these variadic functions with a fixed amount of parameters or
+1. Imitating the behavior of a function e.g. `keyNew()` by calling multiple functions: `keyNew()` and `keySetMeta()` for every meta key/value that was passed.
### Creating the Code-Generator Template
