Elaborate doc/note/initialization.md
diff --git a/doc/note/initialization.md b/doc/note/initialization.md
index 9dc0119..a1f613b 100644
--- a/doc/note/initialization.md
+++ b/doc/note/initialization.md
@@ -1,21 +1,58 @@
-# Zero Initialization
+# Initialization
+
+Outside of the Wuffs base package, every Wuffs struct has an implicit
+`initialize` method, which needs to be called before any other method. In
+Wuffs' C language form, the `initialize` function for the `foo` package's `bar`
+struct is called `wuffs_foo__bar__initialize`. The function takes four
+arguments (or, in C++, the `initialize` method takes three arguments, with the
+implicit `this` pointer argument);
+
+- A pointer to the `wuffs_foo__bar` object: the `this` pointer.
+- The size (in bytes) of that object. Conceptually, this is
+ `sizeof(wuffs_foo__bar{})`, but that expression generally won't compile, as
+ `wuffs_foo__bar` is deliberately an incomplete type. Its size is not part of
+ the stable ABI. Instead, call the `sizeof__wuffs_foo__bar` *function*, whose
+ return value can change across Wuffs versions, even across point releases.
+ For an example, look for `calloc` in the
+ [example/library](/example/library/library.c) program.
+- The Wuffs library version, `WUFFS_VERSION`.
+- Additional flags.
+
+Initialization can fail if the caller and callee disagree on the size or the
+Wuffs version, or if unsupported flag bits are passed.
+
+There are no destructor functions. Just free the memory. Wuffs structs don't
+store or otherwise own file descriptors, pointers to dynamically allocated
+memory or anything else that needs explicit releasing.
+
+As a consequence, to restore a Wuffs object to its initial state (e.g. to
+re-use a Wuffs image decoder's memory to decode a different image), just call
+the `initialize` function again.
+
+
+## Flags
+
+The flags are a bitmask of options. Zero (or equivalently,
+`WUFFS_INITIALIZE__DEFAULT_OPTIONS`) means that none of the options are set.
+
+- The `WUFFS_INITIALIZE__ALREADY_ZEROED` bit tells the `initialize` function to
+ assume that the entire struct has already been zero-initialized. This can
+ make the `initialize` call a little faster.
+- The `WUFFS_INITIALIZE__LEAVE_INTERNAL_BUFFERS_UNINITIALIZED` bit means to
+ partially, not fully, zero-initialize the struct. Again, this can make the
+ call a little faster. See the "Partial Zero-Initialization" section below for
+ details. This bit is ignored if the `WUFFS_INITIALIZE__ALREADY_ZEROED` bit is
+ also set.
+
+
+## Partial Zero-Initialization
Memory-safe programming languages typically initialize their variables and
fields to zero, so that there is no way to read an uninitialized value. By
-default, Wuffs does so too, but in Wuffs' C/C++ form, there is the option to
-leave some struct fields uninitialized (although local variables are always
-zero-initialized), for performance reasons:
-
-```
-uint32_t flags = 0;
-etc
-
-// Setting this flag bit takes the option. Its presence or absence has no
-// effect if the WUFFS_INITIALIZE__ALREADY_ZEROED flag bit is also set.
-flags |= WUFFS_INITIALIZE__LEAVE_INTERNAL_BUFFERS_UNINITIALIZED;
-
-wuffs_foo__bar__initialize(etc, flags);
-```
+default, Wuffs does so too, but in Wuffs' C/C++ form, there is the option (the
+`WUFFS_INITIALIZE__LEAVE_INTERNAL_BUFFERS_UNINITIALIZED` flag bit) to leave
+some struct fields uninitialized (although local variables are always
+zero-initialized), for performance reasons.
With or without this flag bit set, the Wuffs compiler still enforces bounds and
arithmetic overflow checks. It's just that for potentially-uninitialized struct
