Improve comments

5 files changed, 105 insertions, 96 deletions

diff --git a/fgetc.c b/fgetc.c
index aa33a1f..5de851c 100644
--- a/fgetc.c
+++ b/fgetc.c
@@ -19,18 +19,18 @@ static char getc_buffer[GETC_BUFF_SIZE] = { '\0' };
 
 static long next_buffer_pos = 0; /* next free position in the getc buffer */
 
-/* ====================================== */
-/* Get a (possibly pushed-back) character */
-/* ====================================== */
+/* ======================================= */
+/* Gets a (possibly pushed-back) character */
+/* ======================================= */
 int
 my_fgetc(FILE * input)
 {
   return (next_buffer_pos > 0) ? getc_buffer[--next_buffer_pos] : fgetc(input);
 }
 
-/* ============================ */
-/* Push character back on input */
-/* ============================ */
+/* ============================== */
+/* Pushes character back on input */
+/* ============================== */
 void
 my_ungetc(int c)
 {
diff --git a/index.c b/index.c
index 4f92c19..4e40c90 100644
--- a/index.c
+++ b/index.c
@@ -100,9 +100,9 @@ tst_traverse(tst_node_t * p, int (*callback)(void *), int first_call)
 }
 
 /* ======================================================================= */
-/* Traverse the word tst looking for a wchar and build a list of pointers  */
-/* containing all the sub-tst * nodes after these node potentially leading */
-/* to words containing the next wchar os the search string                 */
+/* Traverses the word tst looking for a wchar and build a list of pointers */
+/* containing all the sub-tst potentially leading to words containing the  */
+/* next wchar os the search string.                                        */
 /* ======================================================================= */
 int
 tst_substring_traverse(tst_node_t * p, int (*callback)(void *), int first_call,
@@ -141,11 +141,11 @@ tst_substring_traverse(tst_node_t * p, int (*callback)(void *), int first_call,
   return !!rc;
 }
 
-/* ======================================================================= */
-/* Traverse the word tst looking for a wchar and build a list of pointers  */
-/* containing all the sub-tst * nodes after these node potentially leading */
-/* to words containing the next wchar os the search string                 */
-/* ======================================================================= */
+/* ======================================================================== */
+/* Traverses the word tst looking for a wchar and build a list of pointers  */
+/* containing all the sub-tst nodes potentially leading to words containing */
+/* the next wchar os the search string.                                     */
+/* ======================================================================== */
 int
 tst_fuzzy_traverse(tst_node_t * p, int (*callback)(void *), int first_call,
                    wchar_t w)
@@ -190,9 +190,9 @@ tst_fuzzy_traverse(tst_node_t * p, int (*callback)(void *), int first_call,
   return !!rc;
 }
 
-/* ==================================================================== */
-/* Search a complete string in a ternary tree starting from a root node */
-/* ==================================================================== */
+/* ====================================================================== */
+/* Searches a complete string in a ternary tree starting from a root node */
+/* ====================================================================== */
 void *
 tst_search(tst_node_t * root, wchar_t * w)
 {
@@ -217,11 +217,11 @@ tst_search(tst_node_t * root, wchar_t * w)
   return NULL;
 }
 
-/* =============================================================== */
-/* Search all strings beginning with the same prefix               */
-/* the callback function will be applied to each of theses strings */
-/* returns NULL if no string matched the prefix                    */
-/* =============================================================== */
+/* ================================================================= */
+/* Searches all strings beginning with the same prefix.              */
+/* the callback function will be applied to each of theses strings   */
+/* returns NULL if no string matched the prefix                      */
+/* ================================================================= */
 void *
 tst_prefix_search(tst_node_t * root, wchar_t * w, int (*callback)(void *))
 {
diff --git a/list.c b/list.c
index c6fa148..2b0d405 100644
--- a/list.c
+++ b/list.c
@@ -26,9 +26,9 @@ static ll_node_t *
 ll_partition(ll_node_t * l, ll_node_t * h, int (*comp)(void *, void *),
              void (*swap)(void *, void *));
 
-/* ======================== */
-/* Create a new linked list */
-/* ======================== */
+/* ========================= */
+/* Creates a new linked list */
+/* ========================= */
 ll_t *
 ll_new(void)
 {
@@ -38,9 +38,9 @@ ll_new(void)
   return ret;
 }
 
-/* ======================== */
-/* Initialize a linked list */
-/* ======================== */
+/* ========================= */
+/* Initializes a linked list */
+/* ========================= */
 void
 ll_init(ll_t * list)
 {
@@ -49,9 +49,9 @@ ll_init(ll_t * list)
   list->len  = 0;
 }
 
-/* ==================================================== */
-/* Allocate the space for a new node in the linked list */
-/* ==================================================== */
+/* ===================================================== */
+/* Allocates the space for a new node in the linked list */
+/* ===================================================== */
 ll_node_t *
 ll_new_node(void)
 {
@@ -60,12 +60,12 @@ ll_new_node(void)
   return ret;
 }
 
-/* ==================================================================== */
-/* Append a new node filled with its data at the end of the linked list */
-/* The user is responsible for the memory management of the data        */
-/*                                                                      */
-/* Note: list is assumed to be initialized by ll_new()                  */
-/* ==================================================================== */
+/* ===================================================================== */
+/* Appends a new node filled with its data at the end of the linked list */
+/* The user is responsible for the memory management of the data.        */
+/*                                                                       */
+/* Note: list is assumed to be initialized by ll_new().                  */
+/* ===================================================================== */
 void
 ll_append(ll_t * const list, void * const data)
 {
@@ -90,12 +90,12 @@ ll_append(ll_t * const list, void * const data)
 }
 
 #if 0
-/* =================================================================== */
-/* Put a new node filled with its data at the beginning of the linked  */
-/* list. The user is responsible for the memory management of the data */
-/*                                                                     */
-/* Note: list is assumed to be initialized by ll_new()                 */
-/* =================================================================== */
+/* ==================================================================== */
+/* Puts a new node filled with its data at the beginning of the linked  */
+/* list. The user is responsible for the memory management of the data. */
+/*                                                                      */
+/* Note: list is assumed to be initialized by ll_new().                 */
+/* ==================================================================== */
 void
 ll_prepend(ll_t * const list, void * const data)
 {
@@ -121,9 +121,9 @@ ll_prepend(ll_t * const list, void * const data)
 #endif
 
 #if 0
-/* ======================================================= */
-/* Insert a new node before the specified node in the list */
-/* ======================================================= */
+/* ======================================================== */
+/* Inserts a new node before the specified node in the list */
+/* ======================================================== */
 void
 ll_insert_before(ll_t * const list, ll_node_t * node, void * const data)
 {
@@ -149,9 +149,9 @@ ll_insert_before(ll_t * const list, ll_node_t * node, void * const data)
 #endif
 
 #if 0
-/* ====================================================== */
-/* Insert a new node after the specified node in the list */
-/* ====================================================== */
+/* ======================================================= */
+/* Inserts a new node after the specified node in the list */
+/* ======================================================= */
 void
 ll_insert_after(ll_t * const list, ll_node_t * node, void * const data)
 {
@@ -240,9 +240,9 @@ ll_sort(ll_t * list, int (*comp)(void *, void *),
   ll_quicksort(list->head, list->tail, comp, swap);
 }
 
-/* ================================ */
-/* Remove a node from a linked list */
-/* ================================ */
+/* ================================= */
+/* Removes a node from a linked list */
+/* ================================= */
 int
 ll_delete(ll_t * const list, ll_node_t * node)
 {
@@ -276,11 +276,11 @@ ll_delete(ll_t * const list, ll_node_t * node)
   return 1;
 }
 
-/* =========================================================================*/
-/* Find a node in the list containing data. Return the node pointer or NULL */
-/* if not found.                                                            */
-/* A comparison function must be provided to compare a and b (strcmp like). */
-/* =========================================================================*/
+/* ==========================================================================*/
+/* Finds a node in the list containing data. Return the node pointer or NULL */
+/* if not found.                                                             */
+/* A comparison function must be provided to compare a and b (strcmp like).  */
+/* ==========================================================================*/
 ll_node_t *
 ll_find(ll_t * const list, void * const data,
         int (*cmpfunc)(const void * a, const void * b))
diff --git a/utf8.c b/utf8.c
index c43c563..bf007b2 100644
--- a/utf8.c
+++ b/utf8.c
@@ -17,12 +17,12 @@
 #include "xmalloc.h"
 #include "utf8.h"
 
-/* ======================================================================== */
-/* Unicode (UTF-8) ascii representation interpreter.                        */
-/* The string passed will be altered but will not move in memory            */
-/* All sequence of \uxx, \uxxxx, \uxxxxxx and \uxxxxxxxx will be replace by */
-/* the corresponding UTF-8 character.                                       */
-/* ======================================================================== */
+/* ======================================================================= */
+/* Unicode (UTF-8) ascii representation interpreter.                       */
+/* The string passed will be altered but its address will not change.      */
+/* All hexadecimal sequences of \uxx, \uxxxx, \uxxxxxx and \uxxxxxxxx will */
+/* be replace by the corresponding UTF-8 character.                        */
+/* ======================================================================= */
 void
 utf8_interpret(char * s, langinfo_t * langinfo)
 {
@@ -150,9 +150,9 @@ utf8_interpret(char * s, langinfo_t * langinfo)
 }
 
 /* ========================================================= */
-/* Decode the number of bytes taken by a character (UTF-8)   */
+/* Decodes the number of bytes taken by a UTF-8 glyph.       */
 /* It is the length of the leading sequence of bits set to 1 */
-/* (Count Leading Ones)                                      */
+/* in the first byte.                                        */
 /* ========================================================= */
 int
 utf8_get_length(unsigned char c)
@@ -167,9 +167,9 @@ utf8_get_length(unsigned char c)
     return 4;
 }
 
-/* ================================================== */
-/* Return the byte offset of the nth UTF-8 glyph in s */
-/* ================================================== */
+/* =================================================== */
+/* Returns the byte offset of the nth UTF-8 glyph in s */
+/* =================================================== */
 size_t
 utf8_offset(char * s, size_t n)
 {
@@ -220,7 +220,7 @@ utf8_next(char * p)
 }
 
 /* ============================================================ */
-/* Replace any UTF-8 glyph present in s by a dot in-place       */
+/* Replaces any UTF-8 glyph present in s by a dot in-place      */
 /* s will be modified but its address in memory will not change */
 /* ============================================================ */
 void
@@ -391,9 +391,9 @@ utf8_strprefix(char * d, char * s, long n, long * pos)
   return d;
 }
 
-/* ================================================ */
-/* Convert a UTF-8 glyph string to a wchar_t string */
-/* ================================================ */
+/* ================================================= */
+/* Converts a UTF-8 glyph string to a wchar_t string */
+/* ================================================= */
 wchar_t *
 utf8_strtowcs(char * s)
 {
@@ -424,8 +424,8 @@ utf8_strtowcs(char * s)
 }
 
 /* ============================================================== */
-/* Fill dst whi a lowercase ocopy of src whar the character is an */
-/* ascci one. dsk must be preallocated before the call.           */
+/* Replaces all ASCII characters in src by its lowercase version. */
+/* dst must be preallocated before the call.                      */
 /* ============================================================== */
 void
 utf8_strtolower(char * dst, char * src)
@@ -442,5 +442,6 @@ utf8_strtolower(char * dst, char * src)
     src++;
     dst++;
   }
+
   *dst = '\0';
 }
diff --git a/utils.c b/utils.c
index 2d74cdb..8d164ae 100644
--- a/utils.c
+++ b/utils.c
@@ -22,9 +22,9 @@
 /* Interval functions */
 /* ****************** */
 
-/* ===================== */
-/* Create a new interval */
-/* ===================== */
+/* ====================== */
+/* Creates a new interval */
+/* ====================== */
 interval_t *
 interval_new(void)
 {
@@ -33,10 +33,10 @@ interval_new(void)
   return ret;
 }
 
-/* ====================================== */
-/* Compare 2 intervals as integer couples */
-/* same return values as for strcmp       */
-/* ====================================== */
+/* ======================================= */
+/* Compares 2 intervals as integer couples */
+/* same return values as for strcmp        */
+/* ======================================= */
 int
 interval_comp(void * a, void * b)
 {
@@ -44,20 +44,28 @@ interval_comp(void * a, void * b)
   interval_t * ib = (interval_t *)b;
 
   if (ia->low < ib->low)
+    /* ia: [...      */
+    /* ib:      [... */
     return -1;
   if (ia->low > ib->low)
+    /* ia:      [... */
+    /* ib: [...      */
     return 1;
   if (ia->high < ib->high)
+    /* ia: ...]      */
+    /* ib:      ...] */
     return -1;
   if (ia->high > ib->high)
+    /* ia:      ...] */
+    /* ib: ...]      */
     return 1;
 
   return 0;
 }
 
-/* ================================ */
-/* Swap the values of two intervals */
-/* ================================ */
+/* ================================= */
+/* Swaps the values of two intervals */
+/* ================================= */
 void
 interval_swap(void * a, void * b)
 {
@@ -74,10 +82,10 @@ interval_swap(void * a, void * b)
   ib->high = tmp;
 }
 
-/* ===================================================================== */
-/* Merge the intervals from an interval list in order to get the minimum */
-/* number of intervals to consider.                                      */
-/* ===================================================================== */
+/* ====================================================================== */
+/* Merges the intervals from an interval list in order to get the minimum */
+/* number of intervals to consider.                                       */
+/* ====================================================================== */
 void
 merge_intervals(ll_t * list)
 {
@@ -128,7 +136,7 @@ merge_intervals(ll_t * list)
 /* ***************** */
 
 /* ========================================================================= */
-/* Allocate memory and safely concatenate strings. Stolen from a public      */
+/* Allocates memory and safely concatenate strings. Stolen from a public     */
 /* domain implementation which can be found here:                            */
 /* http://openwall.info/wiki/people/solar/software/public-domain-source-code */
 /* ========================================================================= */
@@ -191,9 +199,9 @@ strprefix(char * str1, char * str2)
   return *str2 == '\0';
 }
 
-/* ======================= */
-/* Trim leading characters */
-/* ======================= */
+/* ======================== */
+/* Trims leading characters */
+/* ======================== */
 void
 ltrim(char * str, const char * trim_str)
 {
@@ -207,7 +215,7 @@ ltrim(char * str, const char * trim_str)
 }
 
 /* ================================================= */
-/* Trim trailing characters                          */
+/* Trims trailing characters                         */
 /* The resulting string will have at least min bytes */
 /* even if trailing spaces remain.                   */
 /* ================================================= */
@@ -281,9 +289,9 @@ isprint8(int i)
   return (c >= 0x20 && c < 0x7f) || (c >= (unsigned char)0xa0);
 }
 
-/* ================================================= */
-/* Private imementation of wcscasecmp wimming in c99 */
-/* ================================================= */
+/* =================================================== */
+/* Private implementation of wcscasecmp wimming in c99 */
+/* =================================================== */
 int
 xwcscasecmp(const wchar_t * s1, const wchar_t * s2)
 {