From: Michael Göhler <somebody.here@gmx.de>
Date: Fri, 12 Sep 2014 23:55:35 +0000 (+0200)
Subject: removed duplicate function + added some comments to header files
X-Git-Url: https://git.danieliu.xyz/?a=commitdiff_plain;h=b416f18295f7edcb5474396a6b26a59fd5ddb1f5;p=smdp.git

removed duplicate function + added some comments to header files
---

diff --git a/cstack.c b/cstack.c
index 6474436..5331328 100644
--- a/cstack.c
+++ b/cstack.c
@@ -29,8 +29,10 @@ char cstack_pop(cstack_t *self) {
     return self->content[self->head--];
 }
 
-char cstack_top(cstack_t *self) {
-    return self->content[self->head];
+int cstack_top(cstack_t *self, char c) {
+    if(self->head >= 0 && self->content[self->head] == c)
+        return 1;
+    return 0;
 }
 
 int cstack_empty(cstack_t *self)  {
diff --git a/include/bitops.h b/include/bitops.h
index e18f3b0..d0225ff 100644
--- a/include/bitops.h
+++ b/include/bitops.h
@@ -1,6 +1,23 @@
 #if !defined( BITOPS_H )
 #define BITOPS_H
 
+/*
+ * Macros to do bit operations on integer variables.
+ *
+ * macro: SET_BIT to set bit at pos of var to 1
+ * macro: CLEAR_BIT to set bit at pos of var to 0
+ * macro: TOGGLE_BIT to toggle bit at pos of var from 1 to 0 and vice versa
+ * macro: CHECK_BIT returns > 0 if bit at pos of var is set to 1
+ *
+ * Example:
+ *      int i = 0;
+ *      i = SET_BIT(i, 2);
+ *      if(CHECK_BIT(i, 2))
+ *          printf("bit 2 is set\n");
+ *      printf("value of i is %d\n", i);
+ *
+ */
+
 #define SET_BIT(var, pos)    ((var) |= (1<<(pos)))
 #define CLEAR_BIT(var, pos)  ((var) &= (~(1<<(pos))))
 #define TOGGLE_BIT(var, pos) ((var) ^= (1<<(pos)))
diff --git a/include/cstack.h b/include/cstack.h
index 315dacb..d6ca407 100644
--- a/include/cstack.h
+++ b/include/cstack.h
@@ -1,6 +1,26 @@
 #if !defined( CSTACK_H )
 #define CSTACK_H
 
+/*
+ * A implementation of a char stack in heap memory.
+ *
+ * struct: cstack_t which defines char stack type in heap memory
+ *
+ * function: cstack_init to intialize struct of type cstack_t
+ * function: cstack_t->push to add one char on top if the stack
+ * function: cstack_t->pop to remove the top char from the stack
+ * function: cstack_t->top to test if the top char is a given char
+ * function: cstack_t->empty to test if the stack is empty
+ * function: cstack_t->delete to free the allocated memory
+ *
+ * Example:
+ *      cstack_t *p = cstack_init();
+ *      (p->push)(p, 'X');
+ *      printf("%c\n", (p->pop)(p));
+ *      (p->delete)(p);
+ *
+ */
+
 typedef struct _cstack_t {
     char *content;
     size_t alloc;
@@ -8,7 +28,7 @@ typedef struct _cstack_t {
     int head;
     void (*push)(struct _cstack_t *self, char c);
     char (*pop)(struct _cstack_t *self);
-    char (*top)(struct _cstack_t *self);
+    int (*top)(struct _cstack_t *self, char c);
     int (*empty)(struct _cstack_t *self);
     void (*delete)(struct _cstack_t *self);
 } cstack_t;
@@ -16,7 +36,7 @@ typedef struct _cstack_t {
 cstack_t *cstack_init();
 void cstack_push(cstack_t *self, char c);
 char cstack_pop(cstack_t *self);
-char cstack_top(cstack_t *self);
+int cstack_top(cstack_t *self, char c);
 int cstack_empty(cstack_t *self);
 void cstack_delete(cstack_t *self);
 
diff --git a/include/cstring.h b/include/cstring.h
index 5e6c3f0..ebaa28f 100644
--- a/include/cstring.h
+++ b/include/cstring.h
@@ -7,7 +7,9 @@
  * struct: cstring_t which defines a expandable c string type in heap memory
  *
  * function: cstring_init to intialize struct of type cstring_t
- * function: cstring_t->expand to add one character to the string
+ * function: cstring_t->expand to add one character to the struct
+ * function: cstring_t->expand_arr to add a string to the struct
+ * function: cstring_t->reset to clear and reuse the struct
  * function: cstring_t->delete to free the allocated memory
  *
  * Example:
diff --git a/include/markdown.h b/include/markdown.h
index 62d1471..655d8f3 100644
--- a/include/markdown.h
+++ b/include/markdown.h
@@ -4,6 +4,18 @@
 /*
  * A implementation of markdown objects.
  *
+ * enum: line_bitmask which enumerates markdown formating bits
+ *
+ * struct: deck_t the root object representing a deck of slides
+ * struct: slide_t a linked list element of type slide contained in a deck
+ * struct: line_t a linked list element of type line contained in a slide
+ *
+ * function: new_deck to initialize a new deck
+ * function: new_slide to initialize a new linked list of type slide
+ * function: next_slide to extend a linked list of type slide by one element
+ * function: new_line to initialize a new linked list of type line
+ * function: next_line to extend a linked list of type line by one element
+ *
  */
 
 #include "cstring.h"
diff --git a/include/parser.h b/include/parser.h
index da63fa1..185fa8d 100644
--- a/include/parser.h
+++ b/include/parser.h
@@ -1,6 +1,23 @@
 #if !defined( PARSER_H )
 #define PARSER_H
 
+/*
+ * Functions necessary to parse a file and transform its content into
+ * a deck of slides containing lines. All based on markdown formating
+ * rules.
+ *
+ * function: markdown_load is the main function which reads a file handle,
+ *           and initializes deck, slides and lines
+ * function: markdown_analyse which is used to identify line wide formating
+ *           rules in given line
+ * function: markdown_debug to print a report of the generated data structure
+ * function: is_utf8 detects multi-byte char
+ * function: length_utf8 calculates the amount of bytes used for a multi-byte
+ *           char
+ * function: next_nonblank, next_blank, next_word to calculate string offset's
+ *
+ */
+
 #include "markdown.h"
 
 #define EXPAND_TABS 4
diff --git a/include/viewer.h b/include/viewer.h
index c5f4530..35f241f 100644
--- a/include/viewer.h
+++ b/include/viewer.h
@@ -1,6 +1,19 @@
 #if !defined( VIEWER_H )
 #define VIEWER_H
 
+/*
+ * Functions necessary to display a deck of slides in different color modes
+ * using ncurses. Only white, red, and blue are supported, as they can be
+ * faded in 256 color mode.
+ *
+ * function: ncurses_display initializes ncurses, defines colors, calculates
+ *           window geometry and handles key strokes
+ * function: add_line detects inline markdown formating and prints line char
+ *           by char
+ * function: fade_in, fade_out implementing color fading in 256 color mode
+ *
+ */
+
 #include <ncurses.h>
 
 #include "parser.h"
@@ -15,7 +28,6 @@
 
 int ncurses_display(deck_t *deck, int notrans, int nofade);
 void add_line(WINDOW *window, int y, int x, line_t *line, int max_cols);
-int is_attron(cstack_t *stack, char c);
 void fade_out(WINDOW *window, int trans, int colors);
 void fade_in(WINDOW *window, int trans, int colors);
 
diff --git a/test/cstack.c b/test/cstack.c
index cf1b504..30d4df3 100644
--- a/test/cstack.c
+++ b/test/cstack.c
@@ -9,13 +9,13 @@ int main(int argc, char *argv[]) {
     printf("INIT: head: %d, size: %zu, alloc: %zu\n", s->head, s->size, s->alloc);
 
     (s->push)(s, 'a');
-    printf("PUSH: char: %c, head: %d, size: %zu, alloc: %zu\n", (s->top)(s), s->head, s->size, s->alloc);
+    printf("PUSH: char: %c, head: %d, size: %zu, alloc: %zu\n", s->content[s->head], s->head, s->size, s->alloc);
 
     (s->push)(s, 'b');
-    printf("PUSH: char: %c, head: %d, size: %zu, alloc: %zu\n", (s->top)(s), s->head, s->size, s->alloc);
+    printf("PUSH: char: %c, head: %d, size: %zu, alloc: %zu\n", s->content[s->head], s->head, s->size, s->alloc);
 
     (s->push)(s, 'c');
-    printf("PUSH: char: %c, head: %d, size: %zu, alloc: %zu\n", (s->top)(s), s->head, s->size, s->alloc);
+    printf("PUSH: char: %c, head: %d, size: %zu, alloc: %zu\n", s->content[s->head], s->head, s->size, s->alloc);
 
     char ch = (s->pop)(s);
     printf("POP: char: %c, head: %d, size: %zu, alloc: %zu\n", ch, s->head, s->size, s->alloc);
@@ -24,10 +24,10 @@ int main(int argc, char *argv[]) {
     printf("POP: char: %c, head: %d, size: %zu, alloc: %zu\n", ch, s->head, s->size, s->alloc);
 
     (s->push)(s, 'd');
-    printf("PUSH: char: %c, head: %d, size: %zu, alloc: %zu\n", (s->top)(s), s->head, s->size, s->alloc);
+    printf("PUSH: char: %c, head: %d, size: %zu, alloc: %zu\n", s->content[s->head], s->head, s->size, s->alloc);
 
     (s->push)(s, 'e');
-    printf("PUSH: char: %c, head: %d, size: %zu, alloc: %zu\n", (s->top)(s), s->head, s->size, s->alloc);
+    printf("PUSH: char: %c, head: %d, size: %zu, alloc: %zu\n", s->content[s->head], s->head, s->size, s->alloc);
 
     while(s->size > 0) {
         ch = (s->pop)(s);
diff --git a/viewer.c b/viewer.c
index d31fa71..4e91b71 100644
--- a/viewer.c
+++ b/viewer.c
@@ -295,7 +295,7 @@ void add_line(WINDOW *window, int y, int x, line_t *line, int max_cols) {
                     if(strchr(special, *c)) {
 
                         // closing special char (or second backslash)
-                        if(is_attron(stack, *c)) {
+                        if((stack->top)(stack, *c)) {
 
                             switch(*c) {
                                 // print escaped backslash
@@ -316,7 +316,7 @@ void add_line(WINDOW *window, int y, int x, line_t *line, int max_cols) {
                             (stack->pop)(stack);
 
                         // treat special as regular char
-                        } else if(is_attron(stack, '\\')) {
+                        } else if((stack->top)(stack, '\\')) {
                             wprintw(window, "%c", *c);
 
                             // remove backslash from stack
@@ -365,16 +365,6 @@ void add_line(WINDOW *window, int y, int x, line_t *line, int max_cols) {
     (stack->delete)(stack);
 }
 
-int is_attron(cstack_t *stack, char c) {
-    // test if char is on top of stack
-    if(stack->head >= 0) {
-        if((stack->top)(stack) == c) {
-            return 1;
-        }
-    }
-    return 0;
-}
-
 void fade_out(WINDOW *window, int trans, int colors) {
     int i; // increment
     if(colors) {