[examples] start type metadata commentary

examples/examples_directory.txt

@@ -34,6 +34,8 @@ EXAMPLES:
 
 
 6. "type metadata" type_metadata/*
+ (Start exploring this example at type_metadata/type_metadata.c)
+
  A common use case for a metaprogramming system in C is to mark up type
  information with metadata. This example shows the "Metadesk way" of
  implementing that use case. This is the biggest example included and closely

examples/type_metadata/type_info.h

@@ -1,9 +1,8 @@
 /*
 ** Example: type metadata
 **
-** This is a hand written header to be included into the final program to
+** This is a hand written header to be included into the final program. It
-** define types that will be used to layout the metadata tables created by the
+** defines the types used to layout the generated tables of metadata.
-** generator.
 **
 ** This file *does not* get included into the generator itself.
 **

examples/type_metadata/type_info_final_program.c

@@ -31,7 +31,7 @@ struct V2F32
 int
 main(int argc, char **argv)
 {
-    
+    // TODO(allen): write example final program
     
     return(0);
 }

examples/type_metadata/type_metadata.c

@@ -1,7 +1,44 @@
 /*
 ** Example: type metadata
 **
-** TODO full commentary
+** This example is full of commentary on strategies for setting up Metadesk
+** programs. There are many many ways a system like this could be built,
+** this example only demonstrates one way. Everything here should be taken as
+** our best attempt to pass on insights about using Metadesk, and not as the
+** "one true way".
+**
+** This example shows what a typical Metadesk based metaprogram for generating
+** type metadata looks like. Metadesk can be used for all sorts of other
+** purposes, managing data tables, authoring content, configuration systems,
+** and more, but a very common reason that a C programmer reaches for a
+** metaprogramming system is to make up for C's lack of type metadata.
+**
+** The "Metadesk way" of solving this problem is to move the hand written type
+** definitions into metadesk files, and to generate the C structs AND the 
+** tables for type metadata from the metaprogram.
+**
+** A more common approach is to mark up C types and create a custom parser
+** for the modified C hybdrid. That approach requires a lot of heuristics to
+** deal with the complex grammar of C code, and is especially hard to make
+** both robust and reusable. The Metadesk way makes the problem a lot more
+** simple, if you are comfortable with generating C types instead of writing
+** them by hand in C.
+**
+**
+** Files:
+**  type_metadata.h - This example is big enough that we pulled out the types
+**                    and function declarations from the metaprogram to keep
+**                    things organized.
+**  type_info.h     - This header is included in the "final program" and
+**                    defines the types that will form the tables of metdata.
+**  type_info_final_program.c - In addition to the metaprogram this example
+**                    includes a "final program", i.e. one that depends on
+**                    generated code. There is more commentary there.
+**  generated/*     - This is the output folder where the generated files
+**                    should be saved by the metaprogram.
+**  types.mdesk     - Sample input for this metaprogram. The code generated
+**                    from this metadesk file will be necessary to make
+**                    type_info_final_program.c compile.
 **
 */
 

examples/type_metadata/types.mdesk

@@ -1,5 +1,7 @@
 /*
-** Setup as input to the type metadata example
+** Example: type metadata
+** 
+** Input for the type definition system setup by type_metadata.c
 */
 
 @type(basic) U32: 4;