FFI: Simplify initializer rules. Clarify docs.

1 files changed, 41 insertions, 0 deletions

diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html
index 598d44c9..4a1b6c11 100644
--- a/doc/ext_ffi_semantics.html
+++ b/doc/ext_ffi_semantics.html
@@ -70,6 +70,47 @@ TODO
 TODO
 </p>
 
+<h2 id="init">Initializers</h2>
+<p>
+Creating a cdata object with <a href="ffi_ext_api.html#ffi_new">ffi.new()</a>
+or the equivalent constructor syntax always initializes its contents,
+too. Different rules apply, depending on the number of optional
+initializers and the C&nbsp;types involved:
+</p>
+<ul>
+<li>If no initializers are given, the object is filled with zero bytes.</li>
+
+<li>Scalar types (numbers and pointers) accept a single initializer.
+The standard <a href="#convert">C&nbsp;type conversion rules</a>
+apply.</li>
+
+<li>Valarrays (complex numbers and vectors) are treated like scalars
+when a single initializer is given. Otherwise they are treated like
+regular arrays.</li>
+
+<li>Aggregate types (arrays and structs) accept either a single
+compound initializer (Lua table or string) or a flat list of
+initializers.</li>
+
+<li>The elements of an array are initialized, starting at index zero.
+If a single initializer is given for an array, it's repeated for all
+remaining elements. This doesn't happen if two or more initializers
+are given: all remaining uninitialized elements are filled with zero
+bytes.</li>
+
+<li>The fields of a <tt>struct</tt> are initialized in the order of
+their declaration. Uninitialized fields are filled with zero
+bytes.</li>
+
+<li>Only the first field of a <tt>union</tt> can be initialized with a
+flat initializer.</li>
+
+<li>Elements or fields which are aggregates themselves are initialized
+with a <em>single</em> initializer, but this may be a compound
+initializer or a compatible aggregate, of course.</li>
+
+</ul>
+
 <h2 id="clib">C Library Namespaces</h2>
 <p>
 A C&nbsp;library namespace is a special kind of object which allows