[doc] added documentation in ast and hashmap headers

3 files changed, 114 insertions, 10 deletions

diff --git a/examples/gcd.imp b/examples/gcd.imp
new file mode 100644
index 0000000..5ab0bbf
--- /dev/null
+++ b/examples/gcd.imp
@@ -0,0 +1,16 @@
+/* computes greatest common divisor (gcd) of a and b */
+procedure gcd(a, b; r) begin
+  if b = 0 then
+    r := a;
+  else
+    q := a;
+    while q >= b do
+      q := q - b;
+    end;
+    gcd(b, q; r);
+  end;
+end;
+
+x := 48;
+y := 18;
+gcd(x, y; result);
diff --git a/include/ast.h b/include/ast.h
index 2d25057..12dce55 100644
--- a/include/ast.h
+++ b/include/ast.h
@@ -2,19 +2,51 @@
 #define AST_H
 
 
+/* AST Node Types */
 typedef enum {
-  NT_SKIP, NT_ASSIGN, NT_SEQ, NT_IF, NT_WHILE,
-  NT_INT, NT_VAR, NT_AOP, NT_BOP, NT_NOT, NT_ROP, NT_LET,
-  NT_PROCDECL, NT_PROCCALL
+  NT_SKIP,     /* nop */
+  NT_ASSIGN,   /* assignment */
+  NT_SEQ,      /* sequential composition */
+  NT_IF,       /* if-then-else block */
+  NT_WHILE,    /* while loop */
+  NT_INT,      /* integer constant */
+  NT_VAR,      /* integer variable */
+  NT_AOP,      /* arithmetic operation */
+  NT_BOP,      /* boolean operation */
+  NT_NOT,      /* boolean not */
+  NT_ROP,      /* relational operation */
+  NT_LET,      /* let-in-end block (i.e. local variable) */
+  NT_PROCDECL, /* procedure declaration */
+  NT_PROCCALL  /* procedure call */
 } NodeType;
 
-typedef enum { AOP_ADD, AOP_SUB, AOP_MUL } AOp;
-typedef enum { BOP_AND, BOP_OR } BOp;
-typedef enum { ROP_EQ, ROP_NE, ROP_LT, ROP_LE, ROP_GT, ROP_GE } ROp;
+/* Arithmetic Operations */
+typedef enum { 
+  AOP_ADD, /* addition */
+  AOP_SUB, /* subtraction */
+  AOP_MUL  /* multiplication */
+} AOp;
 
+/* Boolean Operations */
+typedef enum { 
+  BOP_AND, /* conjunction */
+  BOP_OR   /* disjunction */
+} BOp;
+
+/* Relational Operations */
+typedef enum { 
+  ROP_EQ, /* equals */
+  ROP_NE, /* not equals */
+  ROP_LT, /* less than */
+  ROP_LE, /* less or equals */
+  ROP_GT, /* greater than */
+  ROP_GE  /* greater or equals */
+} ROp;
+
+/* AST Node */
 typedef struct ASTNode {
   NodeType type;
-  union {
+  union { /* specific data for each node type */
     struct { struct ASTNode *var, *aexp; } d_assign;
     struct { struct ASTNode *stm1, *stm2; } d_seq;
     struct { struct ASTNode *bexp, *stm1, *stm2; } d_if;
@@ -31,12 +63,18 @@ typedef struct ASTNode {
   } u;
 } ASTNode;
 
+/* AST Node List (i.e. linked list of AST Nodes) */
 typedef struct ASTNodeList {
   ASTNode *node;
   struct ASTNodeList *next;
 } ASTNodeList;
 
 
+/* 
+  Creates new node of specific type.
+    The caller is responsible for freeing the top-most node, by calling ast_free.
+    Any strings passed to the node are copied (i.e. strdup) and will also automatically be freed.
+*/
 ASTNode *ast_skip(void);
 ASTNode *ast_assign(ASTNode *var, ASTNode *aexp);
 ASTNode *ast_seq(ASTNode *stm1, ASTNode *stm2);
@@ -52,10 +90,20 @@ ASTNode *ast_let(ASTNode *var, ASTNode *aexp, ASTNode *stm);
 ASTNode *ast_procdecl(const char *name, ASTNodeList *args, ASTNodeList *vargs, ASTNode *stm);
 ASTNode *ast_proccall(const char *name, ASTNodeList *args, ASTNodeList *vargs);
 
-
+/* 
+  Creates node list, 
+    Must be used in conjunction with a node that takes a list (i.e. ast_procdecl).
+    Will automatically be freed when the parent node is freed.
+  */
 ASTNodeList *ast_node_list(ASTNode *node, ASTNodeList *list);
 
+/* 
+  Creates a deep copy of a node and it's sub nodes (recursively).
+    caller is responsible for freeing top-most node.
+*/
 ASTNode *ast_clone(ASTNode *node);
+
+/* Recursively frees node and all sub nodes */
 void ast_free(ASTNode *node);
 
 
diff --git a/include/hashmap.h b/include/hashmap.h
index 5273497..57ebafe 100644
--- a/include/hashmap.h
+++ b/include/hashmap.h
@@ -1,21 +1,61 @@
 #ifndef HASHMAP_H
 #define HASHMAP_H
 
-
+/* Hashmap Handle */
 typedef struct HashMap *hashmap_t;
 
+/* Hashmap Key Iterator Handle */
 typedef struct HashMapKeysIter *hashmap_keys_iter_t;
 
-
+/* 
+  Creates hashmap that maps char* to void*.
+    Keys are copied, and will be freed when the hashmap is freed.
+    Elements are not copied, and must be freed by the caller.
+    Caller is responsible for freeing the hashmap using hashmap_free.
+*/
 hashmap_t hashmap_create(void);
+
+/*
+  Frees the hashmap and all keys.
+    Elements are not freed, and must be freed by the caller.
+*/
 void hashmap_free(hashmap_t map);
 
+/* 
+  Looks up element with given key.
+    Returns pointer to element, or NULL if not found.
+*/
 void **hashmap_get(hashmap_t map, const char *key);
+
+/* 
+  Inserts element with given key.
+    If key already exists, the old element is replaced (caller is responsible for freeing beforehand).
+*/
 void hashmap_insert(hashmap_t map, const char *key, void *value);
+
+/* 
+  Deletes element with given key.
+    Caller is responsible for freeing the element.
+    Returns 0 on success, -1 when not found.
+*/
 int hashmap_delete(hashmap_t map, const char *key);
 
+
+/* 
+  Creates iterator for keys.
+    Caller is responsible for freeing the iterator using hashmap_keys_iter_free.
+    Iterator is invalid when the hashmap is modified and must be freed.
+*/
 hashmap_keys_iter_t hashmap_keys_iter_create(hashmap_t map);
+
+/* 
+  Returns next key in the iterator.
+    Returns NULL when there are no more keys.
+    Keys are not copied, and must not be freed.
+*/
 const char *hashmap_keys_iter_next(hashmap_keys_iter_t iter);
+
+/* Frees the iterator. */
 void hashmap_keys_iter_free(hashmap_keys_iter_t iter);