tcon: update and enhance documentation.

diff --git a/ccan/tcon/_info b/ccan/tcon/_info
index 67923a0aecf61f497d38857bc492bb67eb7cde6a..02c0dd8addc3ccc0699f12f298582885c8472752 100644 (file)
--- a/ccan/tcon/_info
+++ b/ccan/tcon/_info
@@ -8,6 +8,54 @@
  * is then a set of macros which check the type canary before calling
  * the generic routines.
  *
  * is then a set of macros which check the type canary before calling
  * the generic routines.
  *

+ * Example:
+ *     #include <ccan/tcon/tcon.h>
+ *     #include <stdio.h>
+ *
+ *     // A simple container class.  Can only contain one thing though!
+ *     struct container {
+ *             void *contents;
+ *     };
+ *     static inline void container_add_raw(struct container *c, void *p)
+ *     {
+ *             c->contents = p;
+ *     }
+ *     static inline void *container_get_raw(struct container *c)
+ *     {
+ *             return c->contents;
+ *     }
+ *
+ *     // This lets the user define their container type; includes a
+ *     // "type canary" to check types against.
+ *     #define DEFINE_TYPED_CONTAINER_STRUCT(name, type) \
+ *             struct name { struct container raw; TCON(type canary); }
+ *
+ *     // These macros make sure the container type and pointer match.
+ *     #define container_add(c, p) \
+ *             container_add_raw(&tcon_check((c), canary, (p))->raw, (p))
+ *     #define container_get(c) \
+ *             tcon_cast((c), canary, container_get_raw(&(c)->raw))
+ *
+ *     // Now, let's define two different containers.
+ *     DEFINE_TYPED_CONTAINER_STRUCT(int_container, int *);
+ *     DEFINE_TYPED_CONTAINER_STRUCT(string_container, char *);
+ *
+ *     int main(int argc, char *argv[])
+ *     {
+ *             struct int_container ic;
+ *             struct string_container sc;
+ *
+ *             // We would get a warning if we used the wrong types...
+ *             container_add(&ic, &argc);
+ *             container_add(&sc, argv[argc-1]);
+ *
+ *             printf("Last arg is %s of %i arguments\n",
+ *                    container_get(&sc), *container_get(&ic) - 1);
+ *             return 0;
+ *     }
+ *     // Given "foo" outputs "Last arg is foo of 1 arguments"
+ *     // Given "foo bar" outputs "Last arg is bar of 2 arguments"
+ *

  * License: Public domain
  *
  * Author: Rusty Russell <rusty@rustcorp.com.au>
  * License: Public domain
  *
  * Author: Rusty Russell <rusty@rustcorp.com.au>

diff --git a/ccan/tcon/tcon.h b/ccan/tcon/tcon.h
index 0f6981d97917009dc816519e1485daaee0d61a59..866c2111e9c942f34c7f51f255f6ab2e3b552cca 100644 (file)
--- a/ccan/tcon/tcon.h
+++ b/ccan/tcon/tcon.h
@@ -9,11 +9,11 @@
  *
  * This declares a _tcon member for a structure.  It should be the
  * last element in your structure; with sufficient compiler support it
  *
  * This declares a _tcon member for a structure.  It should be the
  * last element in your structure; with sufficient compiler support it

- * will not use any actual storage.  tcon_to_raw() will compare
+ * will not use any actual storage.  tcon_check() will compare

  * expressions with one of these "type canaries" to cause warnings if
  * the container is misused.
  *
  * expressions with one of these "type canaries" to cause warnings if
  * the container is misused.
  *

- * A type of "void *" will allow tcon_to_raw() to pass on any (pointer) type.
+ * A type of "void *" will allow tcon_check() to pass on any (pointer) type.

  *
  * Example:
  *     // Simply typesafe linked list.
  *
  * Example:
  *     // Simply typesafe linked list.