- * A vector struct is the "foot part" of an actual containing the
- * applicable implementation variant for this vector, the intended
- * slot size and a root pointer for the indexing structure, which
- * consist of indexing pages according to the variant.
- *
- * Variant 0, 1 and 2, involves indexing pages of 256, 16 and 4
- * pointers respectively. Variant 3 involves a single indexing page of
- * the size of the vector.
+ * \brief The implementation variants.
+ *
+ * - byte_index_levels (0) has 8-bit indexing parts and index pages
+ * with 256 pointers,
+ *
+ * - nibble_index_levels (1) has 4-bit indexing parts and index pages
+ * with 16 pointers,
+ *
+ * - bitpair_index_levels (2) has 2-bit indexing parts and index pages
+ * with 4 pointers,
+ *
+ * - single_index_level (3) has a single page that is sized as the
+ * vector.
+ *
+ * The first three variants are managed by adding/removing full pages
+ * of the indexing tree upon resize and access. The single_index_level
+ * variant is managed by using realloc upon resize. In all cases
+ * shrinking a vector might mean to reclaim items about to be "lost",
+ * if any, via a provided item reclaim callback function. The callback
+ * function may then also veto the shrinking.
+ *
+ * \related vector
+ */
+enum vector_variant {
+ byte_index_levels = 0,
+ nibble_index_levels = 1,
+ bitpair_index_levels = 2,
+ single_index_level = 3
+};
+
+/**
+ * A vector struct is the "foot part" of a representation that
+ * constitutes the implementation variant for a vector abstraction. It
+ * holds the variant indicator, the intended slot size and a root
+ * pointer for the indexing structure, which consist of indexing pages
+ * according to the variant.