From af50453fe474a1e0b26900493427459de82119e7 Mon Sep 17 00:00:00 2001
From: Ralph Ronnquist <ralph.ronnquist@gmail.com>
Date: Sun, 3 Jul 2022 13:40:55 +1000
Subject: [PATCH] editorial

---
 vector/vector.h | 31 ++++++++++++++++++++++---------
 1 file changed, 22 insertions(+), 9 deletions(-)

diff --git a/vector/vector.h b/vector/vector.h
index d3f99b6..b18603f 100644
--- a/vector/vector.h
+++ b/vector/vector.h
@@ -26,23 +26,27 @@
  */
 
 /**
- * This is the general indexing used for vector access.
+ * \brief This is the general indexing used for vector access.
+ * \related vector
  */
 typedef unsigned long vector_index;
 
 /**
- * A vector_page is an array of void* items. Its size depends on the
- * applicable vector variant: 2^(8-variant)
+ * \brief A vector_page is an array of void* items. Its size depends
+ * on the applicable vector variant.
+ * \related vector
  */
 typedef void* vector_page[];
 
 /**
- * A vector is a compound of a size and a vector_page pointer, which
- * when non-null points out the top-most page of the vector indexing
- * tree. The number of levels is derived from its size with level 0
- * being the leaf level of actual content. E.g., a vector larger than
- * 256 items, has at least two levels, and generally N levels may span
- * up to 256^N content entries.
+ * 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.
  */
 typedef struct {
     /**
@@ -51,10 +55,12 @@ typedef struct {
      * Note that variant should not be changed after initialization.
      */
     int variant;
+
     /**
      * The size of the vector.
      */
     vector_index size;
+
     /**
      * The root page of the indexing tree.
      */
@@ -71,6 +77,7 @@ typedef struct {
  * - 3 indicates 64-bit index parts, and 1 page level following the size
  * 
  * The type 3 vector is managed by using realloc.
+ * \related vector
  */
 extern unsigned long VECTOR_SLOTS(vector *pv);
 
@@ -277,6 +284,12 @@ extern void vector_dump(
     vector *pv,
     void (*itemdump)(const vector_index ,const void *));
 
+/**
+ * \brief Sort a vector with quicksort using the provided ordering
+ * collback function.
+ *
+ * \related vector
+ */
 extern void vector_qsort(vector *pv,int (*compar)(const void *,const void *));
 
 /**
-- 
2.39.2