More docs descriptions.

7 files changed, 61 insertions, 56 deletions

diff --git a/docs/clist_api.md b/docs/clist_api.md
index 7073e459..97478435 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -16,29 +16,29 @@ Implemented as a circular singly linked list. Also supports various *splice* fun
 The macro `using_clist()` can be instantiated with 2, 3, 4, or 7 arguments in the global scope.
 Default values are given above for args not specified. `X` is a type tag name and
 will affect the names of all clist types and methods. E.g. declaring `using_clist(my, int);`, `X` should
-be replaced by `my` in all of the following documentation. `using_clist_str()` is a shorthand for:
+be replaced by `my` in all of the following documentation. `using_clist_str()` is a shorthand for
 ```c
 using_clist(str, cstr_t, cstr_del, cstr_compare_raw, const char*, cstr_to_raw, cstr_from)
 ```
 
 ## Types
 
-| Type name             | Type definition                        | Used to represent...                |
-|:----------------------|:---------------------------------------|:------------------------------------|
-| `clist_X`             | `struct { clist_X_node_t* last; }`     | The clist type                      |
-| `clist_X_node_t`      | `struct { ... }`                       | clist node                          |
-| `clist_X_value_t`     | `Value`                                | The clist element type              |
-| `clist_X_input_t`     | `clist_X_value_t`                      | clist input type                    |
-| `clist_X_rawvalue_t`  | `RawValue`                             | clist raw value type                |
-| `clist_X_iter_t`      | `struct { ... }`                       | clist iterator                      |
+| Type name             | Type definition                     | Used to represent...      |
+|:----------------------|:------------------------------------|:--------------------------|
+| `clist_X`             | `struct { clist_X_node_t* last; }`  | The clist type            |
+| `clist_X_node_t`      | `struct { ... }`                    | clist node                |
+| `clist_X_value_t`     | `Value`                             | The clist element type    |
+| `clist_X_input_t`     | `clist_X_value_t`                   | clist input type          |
+| `clist_X_rawvalue_t`  | `RawValue`                          | clist raw value type      |
+| `clist_X_iter_t`      | `struct { ... }`                    | clist iterator            |
 
 
 ## Constants and macros
 
-| Name                       | Value            |
-|:---------------------------|:-----------------|
-|  `clist_inits`             | `{NULL}`         |
-|  `clist_empty(list)`       | `true` if empty  |
+| Name                       | Purpose              |
+|:---------------------------|:---------------------|
+|  `clist_inits`             | Initializer constant |
+|  `clist_empty(list)`       | `true` if list empty |
 
 ## Header file
 
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 71e93514..6582143e 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -30,8 +30,8 @@ Default values are given above for args not specified. `X` is a type tag name an
 will affect the names of all cmap types and methods. E.g. declaring `using_cmap(my, int);`, `X` should
 be replaced by `my` in all of the following documentation.
 
-`using_cmap_strkey(X, ...)` and `using_cmap_strval(X, ...)` are special macros defined with
-`using_cmap()`. The `using_cmap_str()` macro expands to:
+`using_cmap_strkey()` and `using_cmap_strval()` are special macros defined by
+`using_cmap()`. The macro `using_cmap_str()` is a shorthand for
 ```c
 using_cmap(str, cstr_t, cstr_t, cstr_del, cstr_equals_raw, cstr_hash_raw,
            cstr_del, const char*, cstr_to_raw, cstr_from, const char*, cstr_from)
@@ -39,17 +39,17 @@ using_cmap(str, cstr_t, cstr_t, cstr_del, cstr_equals_raw, cstr_hash_raw,
 
 ## Types
 
-| Type name            | Type definition                       | Used to represent...               |
-|:---------------------|:--------------------------------------|:-----------------------------------|
-| `cmap_X`             | `struct { ... }`                      | The cmap type                      |
-| `cmap_X_rawkey_t`    | `RawKey`                              | The raw key type                   |
-| `cmap_X_rawval_t`    | `RawMapped`                           | The raw mapped type                |
-| `cmap_X_key_t`       | `Key`                                 | The key type                       |
-| `cmap_X_mapped_t`    | `Mapped`                              | The mapped type                    |
-| `cmap_X_value_t`     | `struct { ... }`                      | The value type                     |
-| `cmap_X_input_t`     | `struct { ... }`                      | RawKey + RawVal type               |
-| `cmap_X_result_t`    | `struct { ... }`                      | Result of insert/put/emplace       |
-| `cmap_X_iter_t`      | `struct { ... }`                      | Iterator type                      |
+| Type name            | Type definition        | Used to represent...          |
+|:---------------------|:-----------------------|:------------------------------|
+| `cmap_X`             | `struct { ... }`       | The cmap type                 |
+| `cmap_X_rawkey_t`    | `RawKey`               | The raw key type              |
+| `cmap_X_rawval_t`    | `RawMapped`            | The raw mapped type           |
+| `cmap_X_key_t`       | `Key`                  | The key type                  |
+| `cmap_X_mapped_t`    | `Mapped`               | The mapped type               |
+| `cmap_X_value_t`     | `struct { ... }`       | The value type                |
+| `cmap_X_input_t`     | `struct { ... }`       | RawKey + RawVal type          |
+| `cmap_X_result_t`    | `struct { ... }`       | Result of insert/put/emplace  |
+| `cmap_X_iter_t`      | `struct { ... }`       | Iterator type                 |
 
 ## Constants and macros
 
@@ -86,10 +86,10 @@ size_t              cmap_X_size(cmap_X m);
 size_t              cmap_X_bucket_count(cmap_X m);
 size_t              cmap_X_capacity(cmap_X m);
 
-void                cmap_X_push_n(cmap_X* self, const cmap_X_input_t in[], size_t size);
+void                cmap_X_push_n(cmap_X* self, const cmap_X_input_t arr[], size_t size);
 
 cmap_X_result_t     cmap_X_emplace(cmap_X* self, RawKey rkey, RawMapped rmapped);
-cmap_X_result_t     cmap_X_insert(cmap_X* self, cmap_X_input_t in);
+cmap_X_result_t     cmap_X_insert(cmap_X* self, cmap_X_input_t rval);
 cmap_X_result_t     cmap_X_insert_or_assign(cmap_X* self, RawKey rkey, RawMapped rmapped);
 cmap_X_result_t     cmap_X_put(cmap_X* self, RawKey rkey, RawMapped rmapped);
 cmap_X_result_t     cmap_X_put_mapped(cmap_X* self, RawKey rkey, Mapped mapped);
@@ -107,8 +107,7 @@ cmap_X_iter_t       cmap_X_end(cmap_X* self);
 void                cmap_X_next(cmap_X_iter_t* it);
 cmap_X_mapped_t*    cmap_X_itval(cmap_X_iter_t it);
 
-cmap_bucket_t       cmap_X_bucket(const cmap_X* self, const cmap_X_rawkey_t* rawKeyPtr);
-
+cmap_bucket_t       cmap_X_bucket(const cmap_X* self, const cmap_X_rawkey_t* rkeyPtr);
 uint32_t            c_default_hash16(const void *data, size_t len);
 uint32_t            c_default_hash32(const void* data, size_t len);
 ```
diff --git a/docs/cpqueue_api.md b/docs/cpqueue_api.md
index 24e88fc9..76fba64f 100644
--- a/docs/cpqueue_api.md
+++ b/docs/cpqueue_api.md
@@ -9,7 +9,7 @@ This describes the API of the queue type **cpqueue**. Implemented as a heap.
 ```
 The macro `using_cpqueue()` must be instantiated in the global scope.
 **cpqueue** uses normally a **cvec** type as underlying implementation, specified as `ctype`.
-The `heap_variant` argument should be given as `<` or `>`, specifying a *max-heap* or a *min-heap*.
+The `heap_variant` must be given as `<` or `>`, specifying *max-heap* or *min-heap* for the priority queue.
 Note that the function `{ctype}_value_compare(x, y)` defined by the underlying vector type is used to
 compare values (priorities). `X` is a type tag name and will affect the names of all cpqueue types and methods.
 Declaring `using_cpqueue(my, cvec_my, >);`, `X` should be replaced by `my` in the following documentation.
@@ -43,11 +43,11 @@ bool                    cpqueue_X_empty(cpqueue_X pq);
 const
 cpqueue_X_value_t*      cpqueue_X_top(const cpqueue_X* self);
 
-void                    cpqueue_X_push_n(cpqueue_X *self, const cpqueue_X_input_t in[], size_t size);
+void                    cpqueue_X_push_n(cpqueue_X *self, const cpqueue_X_input_t arr[], size_t size);
 void                    cpqueue_X_emplace(cpqueue_X* self, cpqueue_X_rawvalue_t raw);
 void                    cpqueue_X_push(cpqueue_X* self, cpqueue_X_value_t value);
 void                    cpqueue_X_pop(cpqueue_X* self);
-void                    cpqueue_X_erase_at(cpqueue_X* self, size_t i);
+void                    cpqueue_X_erase_at(cpqueue_X* self, size_t idx);
 ```
 
 ## Example
diff --git a/docs/cqueue_api.md b/docs/cqueue_api.md
index 71f1db6f..e6951493 100644
--- a/docs/cqueue_api.md
+++ b/docs/cqueue_api.md
@@ -7,9 +7,8 @@ This describes the API of the queue type **cqueue**.
 ```c
 #define using_cqueue(X, ctype)
 ```
-The macro `using_cqueue()` must be instantiated in the global scope.
-**cqueue** uses normally a **clist** type as underlying implementation, given as `ctype`.
-Default values are given above for args not specified. `X` is a type tag name and
+The macro `using_cqueue()` must be instantiated in the global scope. **cqueue** uses normally
+a **clist** type as underlying implementation, given as `ctype`. `X` is a type tag name and
 will affect the names of all cqueue types and methods. E.g. declaring `using_cqueue(my, clist_my);`,
 `X` should be replaced by `my` in all of the following documentation.
 
@@ -28,7 +27,7 @@ will affect the names of all cqueue types and methods. E.g. declaring `using_cqu
 All cqueue definitions and prototypes may be included in your C source file by including a single header file.
 
 ```c
-#include "stc/cqueue.h"
+#include "stc/cqueue.h" /* includes default underlying implementation header clist.h */
 ```
 
 ## Methods
diff --git a/docs/crandom_api.md b/docs/crandom_api.md
index b645749b..ecc96677 100644
--- a/docs/crandom_api.md
+++ b/docs/crandom_api.md
@@ -1,7 +1,7 @@
 # Module crand: Pseudo Random Number Generators
 
-This describes the API of module **crand**. Contains *pcg32* and an extremely fast *64-bit PRNG* inspired by *sfc64*.
-The PRNG's can generate uniform and normal distributions.
+This describes the API of module **crand**. It contains *pcg32* created by Melissa O'Neill, and an
+*64-bit PRNG* created by Tyge Løvset. The PRNG can generate uniform and normal distributions.
 
 ## Types
 
@@ -52,11 +52,19 @@ All cstr definitions and prototypes may be included in your C source file by inc
 (9)     crand_normal_f64_t      crand_normal_f64_init(double mean, double stddev);
 (10)    double                  crand_normal_f64(crand_rng64_t* rng, crand_normal_f64_t* dist);
 ```
-(1-2) RNG engine initializers. (3) Integer generator, range \[0, 2^64): PRNG copyright Tyge Løvset, NORCE Research, 2020.
+(1-2) RNG engine initializers. (3) Integer generator, range \[0, 2^64),
 (4) Double random number in range \[low, high), 52 bit resolution. (5-8) Initializers and generators of uniform random numbers.
 Integer generator has range \[low, high]. (9-10) Initializer and generator for normal distributed random numbers.
 (9-10) Initializer and generator for normal-distributed random numbers.
 
+The method `crand_i64(crand_rng64_t* rng)` is an extremely fast PRNG suited for parallel usage, featuring
+a Weyl-sequence as part of the state. It is faster than *sfc64*, *wyhash64*, *pcg*, and the *xoroshiro*
+families of RPNGs. It does not require fast multiplication or 128-bit integer operations as it uses only
+shift, xor and addition. The state is 256-bits, but updates only 192 bit per generated number, as the
+last 64 bit holds the Weyl increment. Therefore, it can create 2^63 unique threads with minimum period
+length of 2^64 (expected period length 2^128) per thread. There is no *jump function*, but incrementing
+the Weyl increment by 2, achieves the same goal. Tested with *PractRand* up to 8TB output without issues.
+
 ## Example
 ```c
 #include <stdio.h>
diff --git a/docs/cstack_api.md b/docs/cstack_api.md
index 898b5d8f..433428bf 100644
--- a/docs/cstack_api.md
+++ b/docs/cstack_api.md
@@ -7,10 +7,9 @@ This describes the API of the queue type **cstack**.
 ```c
 #define using_cstack(X, ctype)
 ```
-The macro `using_cstack()` must be instantiated in the global scope.
-**cstack** uses normally a **cvec** type as underlying implementation, given as `ctype`.
-Default values are given above for args not specified. `X` is a type tag name and
-will affect the names of all cstack types and methods. E.g. declaring `using_cstack(my, cvec_my);`,
+The macro `using_cstack()` must be instantiated in the global scope. **cstack** uses normally
+a **cvec** type as underlying implementation, given as `ctype`. `X` is a type tag name and will
+affect the names of all cstack types and methods. E.g. declaring `using_cstack(my, cvec_my);`,
 `X` should be replaced by `my` in all of the following documentation.
 
 ## Types
@@ -28,7 +27,7 @@ will affect the names of all cstack types and methods. E.g. declaring `using_cst
 All cstack definitions and prototypes may be included in your C source file by including a single header file.
 
 ```c
-#include "stc/cstack.h"
+#include "stc/cstack.h" /* includes default underlying implementation header cvec.h */
 ```
 
 ## Methods
diff --git a/docs/cvec_api.md b/docs/cvec_api.md
index 7b542cb3..7004acec 100644
--- a/docs/cvec_api.md
+++ b/docs/cvec_api.md
@@ -30,16 +30,16 @@ using_cvec(str, cstr_t, cstr_del, cstr_compare_raw, const char*, cstr_to_raw, cs
 | `cvec_X_value_t`     | `Value`                             | The cvec value type    |
 | `cvec_X_input_t`     | `cvec_X_value_t`                    | The input type         |
 | `cvec_X_rawvalue_t`  | `RawValue`                          | The raw value type     |
-| `cvec_X_iter_t`      | `struct { cvec_X_value_t* val; }`   | The iterator           |
+| `cvec_X_iter_t`      | `struct { cvec_X_value_t* val; }`   | The iterator type      |
 
 ## Constants and macros
 
-| Name                       | Value            |
-|:---------------------------|:-----------------|
-|  `cvec_inits`              | `{NULL}`         |
-|  `cvec_empty(vec)`         |                  |
-|  `cvec_size(vec)`          |                  |
-|  `cvec_capacity(vec)`      |                  |
+| Name                       | Purpose              |
+|:---------------------------|:---------------------|
+|  `cvec_inits`              | Initializer constant |
+|  `cvec_empty(vec)`         | true if vec is empty |
+|  `cvec_size(vec)`          | return vec length    |
+|  `cvec_capacity(vec)`      | return vec capacity  |
 
 
 ## Header file
@@ -53,12 +53,12 @@ All cvec definitions and prototypes may be included in your C source file by inc
 
 ```c
 cvec_X              cvec_X_init(void);
-cvec_X              cvec_X_with_size(size_t size, Value fill_val);
+cvec_X              cvec_X_with_size(size_t size, Value fill);
 cvec_X              cvec_X_with_capacity(size_t size);
 
 void                cvec_X_clear(cvec_X* self);
 void                cvec_X_reserve(cvec_X* self, size_t cap);
-void                cvec_X_resize(cvec_X* self, size_t size, Value fill_val);
+void                cvec_X_resize(cvec_X* self, size_t size, Value fill);
 void                cvec_X_swap(cvec_X* a, cvec_X* b);
 
 void                cvec_X_del(cvec_X* self);
@@ -68,11 +68,11 @@ size_t              cvec_X_size(cvec_X vec);
 size_t              cvec_X_capacity(cvec_X vec);
 Value               cvec_X_value_from_raw(RawValue val);
 
-cvec_X_value_t*     cvec_X_at(cvec_X* self, size_t i);
+cvec_X_value_t*     cvec_X_at(cvec_X* self, size_t idx);
 cvec_X_value_t*     cvec_X_front(cvec_X* self);
 cvec_X_value_t*     cvec_X_back(cvec_X* self);
 
-void                cvec_X_push_n(cvec_X *self, const cvec_X_input_t in[], size_t size);
+void                cvec_X_push_n(cvec_X *self, const cvec_X_input_t arr[], size_t size);
 void                cvec_X_emplace_back(cvec_X* self, RawValue val);
 void                cvec_X_push_back(cvec_X* self, Value value);
 void                cvec_X_pop_back(cvec_X* self);