Improved documentation of template parameters for all containers.

13 files changed, 66 insertions, 31 deletions

diff --git a/docs/carc_api.md b/docs/carc_api.md
index 04856622..18bf52c7 100644
--- a/docs/carc_api.md
+++ b/docs/carc_api.md
@@ -20,11 +20,15 @@ See similar c++ class [std::shared_ptr](https://en.cppreference.com/w/cpp/memory
 ## Header file and declaration
 
 ```c
+#define i_type            // full typename of the carc
 #define i_val             // value: REQUIRED
-#define i_cmp             // three-way compare two i_val* : REQUIRED IF i_val is a non-integral type
-#define i_valdrop         // destroy value func - defaults to empty destruct
-#define i_tag             // defaults to i_val
+
+#define i_valraw          // convertion "raw" type - defaults to i_val
+#define i_valto           // convertion func i_val* => i_valraw: REQUIRED IF i_valraw defined.
+#define i_valfrom         // convertion func i_valraw => i_val
+      
 #define i_opt c_no_atomic // Non-atomic reference counting, like Rust Rc.
+#define i_tag             // alternative typename: carc_{i_tag}. i_tag defaults to i_val
 #include <stc/carc.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
diff --git a/docs/carray_api.md b/docs/carray_api.md
index cede295e..e12cbc4f 100644
--- a/docs/carray_api.md
+++ b/docs/carray_api.md
@@ -9,11 +9,10 @@ See the c++ class [boost::multi_array](https://www.boost.org/doc/libs/release/li
 ## Header file and declaration
 
 ```c
+#define i_type      // full typename of the container
 #define i_val       // value: REQUIRED
 #define i_valdrop   // destroy value func - defaults to empty destruct
 #define i_valclone  // REQUIRED IF valdrop is defined.
-#define i_tag       // defaults to i_val
-
 #include <stc/carr2.h> // or <stc/carr3.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
diff --git a/docs/cbox_api.md b/docs/cbox_api.md
index 79911876..710c82f7 100644
--- a/docs/cbox_api.md
+++ b/docs/cbox_api.md
@@ -14,14 +14,18 @@ See similar c++ class [std::unique_ptr](https://en.cppreference.com/w/cpp/memory
 ## Header file and declaration
 
 ```c
+#define i_type          // full typename of the cbox
 #define i_val           // value: REQUIRED
 #define i_cmp           // three-way compare two i_val* : REQUIRED IF i_val is a non-integral type
 #define i_valdrop       // destroy value func - defaults to empty destruct
 #define i_valclone      // REQUIRED if i_valdrop is defined, unless 'i_opt c_no_clone' is defined.
-#define i_valraw        // convertion type (lookup)
+
+#define i_valraw        // convertion type (lookup): default to {i_val}
+#define i_valto         // convertion func i_val* => i_valraw: REQUIRED IF i_valraw defined.
 #define i_valfrom       // from-raw func.
-#define i_valto         // to-raw func.
-#define i_tag           // type name tag, defaults to i_val
+
+#define i_valclass      // alt. to i_val: REQUIRES that {i_val}_clone, {i_val}_drop, {i_valraw}_cmp exist.
+#define i_tag           // alternative typename: cbox_{i_tag}. i_tag defaults to i_val
 #include <stc/cbox.h>    
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
diff --git a/docs/cdeq_api.md b/docs/cdeq_api.md
index cfd5565e..7ce4c7f1 100644
--- a/docs/cdeq_api.md
+++ b/docs/cdeq_api.md
@@ -8,14 +8,17 @@ See the c++ class [std::deque](https://en.cppreference.com/w/cpp/container/deque
 ## Header file and declaration
 
 ```c
+#define i_type      // full typename of the container
 #define i_val       // value: REQUIRED
 #define i_cmp       // three-way compare two i_valraw* : REQUIRED IF i_valraw is a non-integral type
 #define i_valdrop   // destroy value func - defaults to empty destruct
 #define i_valclone  // REQUIRED IF i_valdrop defined
+
 #define i_valraw    // convertion "raw" type - defaults to i_val
 #define i_valfrom   // convertion func i_valraw => i_val
 #define i_valto     // convertion func i_val* => i_valraw
-#define i_tag       // defaults to i_val
+
+#define i_tag       // alternative typename: cdeq_{i_tag}. i_tag defaults to i_val
 #include <stc/cdeq.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
diff --git a/docs/clist_api.md b/docs/clist_api.md
index 0d20941a..aae72224 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -22,14 +22,16 @@ See the c++ class [std::list](https://en.cppreference.com/w/cpp/container/list)
 ## Header file and declaration
 
 ```c
+#define i_type      // container type name (default: clist_{i_val})
 #define i_val       // value: REQUIRED
 #define i_cmp       // three-way compare two i_valraw* : REQUIRED IF i_valraw is a non-integral type
 #define i_valdrop   // destroy value func - defaults to empty destruct
 #define i_valclone  // REQUIRED IF i_valdrop defined
-#define i_valraw    // convertion "raw" type - defaults to i_val
+
+#define i_valraw    // convertion "raw" type (default: {i_val})
 #define i_valto     // convertion func i_val* => i_valraw
 #define i_valfrom   // convertion func i_valraw => i_val
-#define i_tag       // defaults to i_val
+#define i_tag       // alternative typename: cpque_{i_tag}. i_tag defaults to i_val
 #include <stc/clist.h>
 ```
 
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 802bfa00..48aa7e0d 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -17,15 +17,15 @@ See the c++ class [std::unordered_map](https://en.cppreference.com/w/cpp/contain
 ## Header file and declaration
 
 ```c
+#define i_type      // container type name (default: cmap_{i_key})
 #define i_key       // hash key: REQUIRED
 #define i_val       // map value: REQUIRED
 #define i_hash      // hash func i_keyraw*: REQUIRED IF i_keyraw is non-pod type
 #define i_eq        // equality comparison two i_keyraw*: REQUIRED IF i_keyraw is a
-                    // non-integral type. Three-way i_cmp may be specified alternatively.
-#define i_size      // size_t or uint32_t(default). If defined, table expand 2x (else 1.5x)  
+                    // non-integral type. Three-way i_cmp may alternatively be specified.
 
 #define i_keydrop   // destroy key func - defaults to empty destruct
-#define i_keyclone  // REQUIRED IF i_valdrop defined
+#define i_keyclone  // REQUIRED IF i_keydrop defined
 #define i_keyraw    // convertion "raw" type - defaults to i_key
 #define i_keyfrom   // convertion func i_keyraw => i_key
 #define i_keyto     // convertion func i_key* => i_keyraw
@@ -36,8 +36,10 @@ See the c++ class [std::unordered_map](https://en.cppreference.com/w/cpp/contain
 #define i_valfrom   // convertion func i_valraw => i_val
 #define i_valto     // convertion func i_val* => i_valraw
 
-#define i_tag       // typename tag. defaults to i_key
-#define i_type      // full typename of the container
+#define i_size      // default: uint32_t. If defined, table expand 2x (else 1.5x)
+#define i_hash_functor // advanced, see examples/cpque.c for similar usage.
+#define i_eq_functor // advanced, see examples/cpque.c for similar usage.
+#define i_tag       // alternative typename: cmap_{i_tag}. i_tag defaults to i_val
 #include <stc/cmap.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
diff --git a/docs/cpque_api.md b/docs/cpque_api.md
index 8b990be8..5f234892 100644
--- a/docs/cpque_api.md
+++ b/docs/cpque_api.md
@@ -8,15 +8,18 @@ See the c++ class [std::priority_queue](https://en.cppreference.com/w/cpp/contai
 ## Header file and declaration
 
 ```c
+#define i_type      // define type name of the container (default cpque_{i_val})
 #define i_val       // value: REQUIRED
-#define i_cmp       // three-way compare two i_val* : REQUIRED IF i_val/i_valraw is a non-integral type
+#define i_less      // compare two i_val* : REQUIRED IF i_val/i_valraw is a non-integral type
 #define i_valdrop   // destroy value func - defaults to empty destruct
 #define i_valclone  // REQUIRED IF i_valdrop defined
+
 #define i_valraw    // convertion type
 #define i_valfrom   // convertion func i_valraw => i_val
 #define i_valto     // convertion func i_val* => i_valraw.
-#define i_tag       // defaults to i_val
-#define i_type      // container type name
+
+#define i_less_functor // takes self as first argument. See examples/cpque.c for usage.
+#define i_tag       // alternative typename: cpque_{i_tag}. i_tag defaults to i_val
 #include <stc/cpque.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
diff --git a/docs/cqueue_api.md b/docs/cqueue_api.md
index a8be9e86..89ca7d5c 100644
--- a/docs/cqueue_api.md
+++ b/docs/cqueue_api.md
@@ -7,14 +7,16 @@ See the c++ class [std::queue](https://en.cppreference.com/w/cpp/container/queue
 
 ## Header file and declaration
 ```c
+#define i_type      // container type name (default: cset_{i_key})
 #define i_val       // value: REQUIRED
-#define i_cmp       // three-way compare two i_valraw* : REQUIRED IF i_valraw is a non-integral type
 #define i_valdrop   // destroy value func - defaults to empty destruct
 #define i_valclone  // REQUIRED IF i_valdrop defined
+
 #define i_valraw    // convertion "raw" type - defaults to i_val
 #define i_valfrom   // convertion func i_valraw => i_val
 #define i_valto     // convertion func i_val* => i_valraw
-#define i_tag       // defaults to i_val
+
+#define i_tag       // alternative typename: cqueue_{i_tag}. i_tag defaults to i_val
 #include <stc/cqueue.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
diff --git a/docs/cset_api.md b/docs/cset_api.md
index 07eada22..266895be 100644
--- a/docs/cset_api.md
+++ b/docs/cset_api.md
@@ -7,15 +7,21 @@ A **cset** is an associative container that contains a set of unique objects of
 ## Header file and declaration
 
 ```c
+#define i_type      // container type name (default: cset_{i_key})
 #define i_key       // hash key: REQUIRED.
 #define i_hash      // hash func: REQUIRED IF i_keyraw is a non-pod type.
-#define i_eq        // equality comparison two i_keyraw*: !i_cmp will be used if not defined.
+#define i_eq        // equality comparison two i_keyraw*: !i_cmp is used if not defined.
 #define i_keydrop   // destroy key func - defaults to empty destruct
+#define i_keyclone  // REQUIRED IF i_keydrop defined
+
 #define i_keyraw    // convertion "raw" type - defaults to i_key
 #define i_keyfrom   // convertion func i_keyraw => i_key - defaults to plain copy
 #define i_keyto     // convertion func i_key* => i_keyraw - defaults to plain copy
-#define i_tag       // typename tag. defaults to i_key
-#define i_type      // full typename of the container
+
+#define i_size      // default: uint32_t. If defined, table expand 2x (else 1.5x)
+#define i_hash_functor // advanced, see examples/cpque.c for similar usage.
+#define i_eq_functor // advanced, see examples/cpque.c for similar usage.
+#define i_tag       // alternative typename: cmap_{i_tag}. i_tag defaults to i_val
 #include <stc/cset.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
diff --git a/docs/csmap_api.md b/docs/csmap_api.md
index 38fd4bf4..bb0253c7 100644
--- a/docs/csmap_api.md
+++ b/docs/csmap_api.md
@@ -15,6 +15,7 @@ See the c++ class [std::map](https://en.cppreference.com/w/cpp/container/map) fo
 ## Header file and declaration
 
 ```c
+#define i_type      // container type name (default: cmap_{i_key})
 #define i_key       // key: REQUIRED
 #define i_val       // value: REQUIRED
 #define i_cmp       // three-way compare two i_keyraw* : REQUIRED IF i_keyraw is a non-integral type
@@ -31,8 +32,8 @@ See the c++ class [std::map](https://en.cppreference.com/w/cpp/container/map) fo
 #define i_valfrom   // convertion func i_valraw => i_val
 #define i_valto     // convertion func i_val* => i_valraw
 
-#define i_tag       // typename tag. defaults to i_key
-#define i_type      // full typename of the container
+#define i_cmp_functor // advanced, see examples/cpque.c for similar usage.
+#define i_tag       // alternative typename: csmap_{i_tag}. i_tag defaults to i_val
 #include <stc/csmap.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
diff --git a/docs/csset_api.md b/docs/csset_api.md
index 82b8eb09..6b2bdfdf 100644
--- a/docs/csset_api.md
+++ b/docs/csset_api.md
@@ -8,14 +8,18 @@ See the c++ class [std::set](https://en.cppreference.com/w/cpp/container/set) fo
 ## Header file and declaration
 
 ```c
+#define i_type      // full typename of the container
 #define i_key       // key: REQUIRED
 #define i_cmp       // three-way compare two i_keyraw* : REQUIRED IF i_keyraw is a non-integral type
 #define i_keydrop   // destroy key func - defaults to empty destruct
+#define i_keyclone  // REQUIRED IF i_keydrop defined
+
 #define i_keyraw    // convertion "raw" type - defaults to i_key
 #define i_keyfrom   // convertion func i_keyraw => i_key - defaults to plain copy
 #define i_keyto     // convertion func i_key* => i_keyraw - defaults to plain copy
-#define i_tag       // typename tag. defaults to i_key
-#define i_type      // full typename of the container
+
+#define i_cmp_functor // advanced, see examples/cpque.c for similar usage.
+#define i_tag       // alternative typename: csset_{i_tag}. i_tag defaults to i_val
 #include <stc/csset.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
diff --git a/docs/cstack_api.md b/docs/cstack_api.md
index 2a61aecf..e8423385 100644
--- a/docs/cstack_api.md
+++ b/docs/cstack_api.md
@@ -8,14 +8,16 @@ See the c++ class [std::stack](https://en.cppreference.com/w/cpp/container/stack
 ## Header file and declaration
 
 ```c
+#define i_type      // full typename of the container
 #define i_val       // value: REQUIRED
-#define i_cmp       // three-way compare two i_valraw* : REQUIRED IF i_valraw is a non-integral type
 #define i_valdrop   // destroy value func - defaults to empty destruct
 #define i_valclone  // REQUIRED IF i_valdrop defined
+
 #define i_valraw    // convertion "raw" type - defaults to i_val
 #define i_valfrom   // convertion func i_valraw => i_val
 #define i_valto     // convertion func i_val* => i_valraw
-#define i_tag       // defaults to i_val name
+
+#define i_tag       // alternative typename: cstack_{i_tag}. i_tag defaults to i_val
 #include <stc/cstack.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
diff --git a/docs/cvec_api.md b/docs/cvec_api.md
index f4cedb75..d19607c6 100644
--- a/docs/cvec_api.md
+++ b/docs/cvec_api.md
@@ -12,14 +12,17 @@ See the c++ class [std::vector](https://en.cppreference.com/w/cpp/container/vect
 ## Header file and declaration
 
 ```c
+#define i_type      // full typename of the container
 #define i_val       // value: REQUIRED
 #define i_cmp       // three-way compare two i_valraw* : REQUIRED IF i_valraw is a non-integral type
 #define i_valdrop   // destroy value func - defaults to empty destruct
 #define i_valclone  // REQUIRED IF i_valdrop defined
+
 #define i_valraw    // convertion "raw" type - defaults to i_val
 #define i_valfrom   // convertion func i_valraw => i_val
 #define i_valto     // convertion func i_val* => i_valraw
-#define i_tag       // defaults to i_val
+
+#define i_tag       // alternative typename: cvec_{i_tag}. i_tag defaults to i_val
 #include <stc/cvec.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.