Gen-CID test_lib - documentation

gen/data/input/test_data/enums.h

@@ -1,6 +1,11 @@
 #ifndef ENUMS_H
 #define ENUMS_H
 
+// Enums
+// =====
+// Enums only have the item qualifier I and A,
+// so their combinations are simple.
+//
 // Covered combinations
 // ====================
 // _IE   = incomplete enum without an alias

gen/data/input/test_data/structs.h

@@ -2,7 +2,7 @@
 #define STRUCTS_H
 
 // Structs
-// -------
+// =======
 // For structs, a combination is needed to define the type of struct
 // IS   = Struct (Empty or incomplete, neither primitive nor complex)
 // PS   = Primitive struct (struct containing only primitive types)
@@ -10,9 +10,8 @@
 // NPS  = Nested primitive struct
 
 
-// Some Possible combinations
-// ==========================
-//
+// Covered combinations
+// ====================
 // _IS   = incomplete struct without a typedef (forward decl)
 // IS    = incomplete struct
 // AIS   = alias of an incomplete struct
@@ -57,8 +56,6 @@
 // _NENHS = nested enum in nested hosting struct
 
 
-// Covered combinations
-// =====================
 // _IS   = incomplete struct without a typedef (forward decl)
 struct _IS;
 

gen/data/input/test_data/test_lib.h

@@ -7,8 +7,72 @@
 #include "functions.h"
 #include "vars.h"
 
-// Types
-// =====
+// Gen-CID
+// =======
+// CIDG generates a C Interface Defintion file (json) given the inputs:
+// * headerfile
+// * list of function names needed
+// * list of var names needed
+// The generator searches each function/var in the headerfile (recursively) and collects all the
+// types needed (var type, return type, parm types).
+// As structs can contain further types, these dependent types need to be resolved
+// recursively.
+// Finally, the collected types will be resolved to their final underlying type.
+// If a type is primitive, nothing needs to be done its already defined.
+// But types of typekind struct or enum need to be defined.
+// Their definition will be searched for in the headerfile and included in the interface definition
+// The CID file contains all the information needed to represet:
+// * functions
+// * vars
+// * structs
+// * enums
+// Well enough so they can be expressed in pyBind11
+// use "pyBind11-CID" to generate the pyBind11 code out of the CID file.
+//
+// Gen-CID test library
+// --------------------
+// This here is the test main test library for Gen-CID.
+// The C language is broken down into its components and common pattern.
+// It is a humble attempt to cover all possible combinations that can be created in the
+// C language. (like, struct containing` primitive, struct containing struct, typedef chains,
+// etc..).
+// Please note, that pointer types have not been addressed yet (at all)
+//
+// The intended use of this test lib is: If you encounter a scenario using Gen-CID that poses problem
+// it is most likely that the scenario can be reproduced using this test lib pretty easily.
+// lets say you Gen-CID a function with sig:
+// TT_E(*)(ACCS), where:
+//      TT_E = typedef of typedef of an enum without an alias.
+//      ACCS = Alias to a complex struct containing another complex struct
+// these types exist already along with a systematic permutation of possible types that amount
+// to over 100 of types.
+// just write your func/var using these types and debug the generation.
+
+
+// The CID format deals with items. Everything is an item.
+// There are qualifiers that can be used and combined to define an item. (list below)
+// e.g PS = primitive struct that possibly has a typedef
+//
+// Of all the possible combinations, not all are valid (C lang). Its a futile attempt
+// trying to cover all the valid ones. But an effort has been made to cover the most
+// of the valid combinations.
+// Combination of structs, enums and typedefs are systematically explored in the files:
+// * structs.h
+// * enums.h
+// * typedefs.h
+//
+// For all the types defined the file:
+// * vars.h
+// contains an instance of each.
+//
+// for all the possible function signature, well with a 100 types,
+// we can create 10000 different sigantures using 1 ret and 1 arg.
+// Therefore, no functions have been defined.
+// define them when you are interested in the combination, and Gen-CID the defintion.
+
+
+// Item Qualitfier
+// ===============
 // V     = Void                                     already defined
 // P     = Primitive Type                           already defined
 // S     = Struct                                   -> struct.h
@@ -22,8 +86,9 @@
 //
 // func_ = function                                 -> functions.h
 // var_  = variable                                 -> vars.h
-
-
+//
+// prefixed underline (e.g _E) means no typedef/alias exists for this item (enum in this case)
+//
 // Alias vs. Typedef
 // -----------------
 // aliased means direct typedef directly, like

gen/data/input/test_data/typedefs.h

@@ -4,54 +4,17 @@
 #include "structs.h"
 #include "enums.h"
 
-// Covered combinations
-// ====================
-//
-// typedef Void
-// ------------
-// TV      = Typedef of Void
-//
-// typedef primitive
-// -------------------
-// TP      = Typedef of primitive type
-//
-// typedef structs
-// ----------------
-// T_IS    = typedef of an incomplete struct without a typedef (forward decl)
-// TIS     = typedef of an incomplete struct
-// TAIS    = typedef of an alias of an incomplete struct
-// T_PS    = typedef of a primitive struct without a an alias
-// TPS     = typedef of a primitive struct
-// TAPS    = typedef of an Alias of primitive struct
-//
-// nested struct
-// T_NPS   = typedef of a nested primitive struct without an alias
-// T_NNPS  = typedef of a nested primitive struct without an alias
-//
-// (typedef) enum
-// ----------------
-// T_IE    = typedef of an incomplete enum without an alias
-// TIE     = typedef of an incomplete enum
-// TAIE    = typedef of an alias of an incomplete enum
-// T_E     = typedef of an enum without an alias
-// TE      = typedef of an enum
-// TAE     = typedef of an alias of an enum
-
-// TT*     = typedef of typedef of anything
-
+// Typedefs
+// ========
+// Typedefs are simply applied to all defined enums and structs, and the
+// their respecitve "alias".
+// Then a typedef os applied to every typedef (TT*)
 
-// typedef Void
-// ------------
-// TV      = Typedef of Void
 typedef void TV;
-
-// typedef primitive
-// -------------------
-// TP      = Typedef of primitive type
 typedef int TP;
 
-// typedef structs
-// ----------------
+// typedef struct
+// --------------
 // T_IS    = typedef of an incomplete struct without a typedef (forward decl)
 typedef struct _IS T_IS;
 // TIS     = typedef of an incomplete struct
@@ -113,9 +76,8 @@ typedef struct _HS1 T_HS1;
 typedef enum _NEHS T_NEHS;
 
 
-
-// (typedef) enum
-// ----------------
+// typedef enum
+// ------------
 // T_IE    = typedef of an incomplete enum without an alias
 typedef enum _IE T_IE;
 // TIE     = typedef of an incomplete enum
@@ -130,8 +92,7 @@ typedef enum E TE;
 typedef AE TAE;
 
 
-// TT*     = typedef of all typedefs
-
+// TT*     = typedef of all typedefs above
 typedef TV TTV;
 typedef TP TTP;
 typedef T_IS TT_IS;