doxygen fixes

git-svn-id: https://gnunet.org/svn/gnunet@22298 140774ce-b5e7-0310-ab8b-a85725594a96

1 files changed, 99 insertions, 67 deletions

diff --git a/src/regex/regex.c b/src/regex/regex.c
index 6d4a5b22d2..411c72c08b 100644
--- a/src/regex/regex.c
+++ b/src/regex/regex.c
@@ -28,6 +28,9 @@
 #include "gnunet_regex_lib.h"
 #include "regex.h"
 
+/**
+ * Constant for how many bits the initial string regex should have.
+ */
 #define INITIAL_BITS 10
 
 /**
@@ -118,9 +121,9 @@ struct GNUNET_REGEX_Automaton
   char *regex;
 
   /**
-   * Computed regex (result of RX->NFA->DFA->RX)
+   * Canonical regex (result of RX->NFA->DFA->RX)
    */
-  char *computed_regex;
+  char *canonical_regex;
 };
 
 /**
@@ -282,9 +285,20 @@ struct GNUNET_REGEX_StateSet
 /*
  * Debug helper functions
  */
+
+/**
+ * Print all the transitions of state 's'.
+ *
+ * @param s state for which to print it's transitions.
+ */
 void
-debug_print_transitions (struct GNUNET_REGEX_State *);
+debug_print_transitions (struct GNUNET_REGEX_State *s);
 
+/**
+ * Print information of the given state 's'.
+ *
+ * @param s state for which debug information should be printed.
+ */
 void
 debug_print_state (struct GNUNET_REGEX_State *s)
 {
@@ -304,6 +318,11 @@ debug_print_state (struct GNUNET_REGEX_State *s)
   debug_print_transitions (s);
 }
 
+/**
+ * Print debug information for all states contained in the automaton 'a'.
+ *
+ * @param a automaton for which debug information of it's states should be printed.
+ */
 void
 debug_print_states (struct GNUNET_REGEX_Automaton *a)
 {
@@ -313,6 +332,11 @@ debug_print_states (struct GNUNET_REGEX_Automaton *a)
     debug_print_state (s);
 }
 
+/**
+ * Print debug information for given transition 't'.
+ *
+ * @param t transition for which to print debug info.
+ */
 void
 debug_print_transition (struct Transition *t)
 {
@@ -351,12 +375,13 @@ debug_print_transitions (struct GNUNET_REGEX_State *s)
     debug_print_transition (t);
 }
 
+
 /**
  * Recursive function doing DFS with 'v' as a start, detecting all SCCs inside
  * the subgraph reachable from 'v'. Used with scc_tarjan function to detect all
  * SCCs inside an automaton.
  *
- * @param ctx context
+ * @param scc_counter counter for numbering the sccs
  * @param v start vertex
  * @param index current index
  * @param stack stack for saving all SCCs
@@ -408,12 +433,12 @@ scc_tarjan_strongconnect (unsigned int *scc_counter,
   }
 }
 
+
 /**
  * Detect all SCCs (Strongly Connected Components) inside the given automaton.
  * SCCs will be marked using the scc_id on each state.
  *
- * @param ctx context
- * @param a automaton
+ * @param a the automaton for which SCCs should be computed and assigned.
  */
 static void
 scc_tarjan (struct GNUNET_REGEX_Automaton *a)
@@ -781,10 +806,8 @@ typedef void (*GNUNET_REGEX_traverse_action) (void *cls, unsigned int count,
  * @param action_cls closure for action
  */
 static void
-automaton_state_traverse (struct GNUNET_REGEX_State *s,
-                          unsigned int *count,
-                          GNUNET_REGEX_traverse_action action,
-			  void *action_cls)
+automaton_state_traverse (struct GNUNET_REGEX_State *s, unsigned int *count,
+                          GNUNET_REGEX_traverse_action action, void *action_cls)
 {
   struct Transition *t;
 
@@ -795,7 +818,7 @@ automaton_state_traverse (struct GNUNET_REGEX_State *s,
     action (action_cls, *count, s);
   (*count)++;
   for (t = s->transitions_head; NULL != t; t = t->next)
-    automaton_state_traverse (t->to_state, count, action, action_cls);  
+    automaton_state_traverse (t->to_state, count, action, action_cls);
 }
 
 
@@ -809,8 +832,7 @@ automaton_state_traverse (struct GNUNET_REGEX_State *s,
  */
 static void
 automaton_traverse (struct GNUNET_REGEX_Automaton *a,
-                    GNUNET_REGEX_traverse_action action,
-		    void *action_cls)
+                    GNUNET_REGEX_traverse_action action, void *action_cls)
 {
   unsigned int count;
   struct GNUNET_REGEX_State *s;
@@ -827,7 +849,7 @@ automaton_traverse (struct GNUNET_REGEX_Automaton *a,
  * using it to generate a regex.
  *
  * Currently only tests for first and last characters being '()' respectively.
- * FIXME: What about "(ab)|(cd)"?  
+ * FIXME: What about "(ab)|(cd)"?
  *
  * @param str string
  *
@@ -842,10 +864,9 @@ needs_parentheses (const char *str)
   const char *pos;
   unsigned int cnt;
 
-  if ( (NULL == str) ||
-       ((slen = strlen(str)) < 2) )
+  if ((NULL == str) || ((slen = strlen (str)) < 2))
     return GNUNET_NO;
-  
+
   if ('(' != str[0])
     return GNUNET_YES;
   cnt = 1;
@@ -859,7 +880,7 @@ needs_parentheses (const char *str)
       return GNUNET_YES;
     }
     op = strchr (pos, '(');
-    if ( (NULL != op) && (op < cl))
+    if ((NULL != op) && (op < cl))
     {
       cnt++;
       pos = op + 1;
@@ -879,7 +900,7 @@ needs_parentheses (const char *str)
  * You need to GNUNET_free the returned string.
  *
  * Currently only tests for first and last characters being '()' respectively.
- * FIXME: What about "(ab)|(cd)"?  
+ * FIXME: What about "(ab)|(cd)"?
  *
  * @param str string, free'd or re-used by this function, can be NULL
  *
@@ -891,7 +912,8 @@ remove_parentheses (char *str)
 {
   size_t slen;
 
-  if ( (NULL == str) || ('(' != str[0]) || (str[(slen = strlen(str)) - 1] != ')') )
+  if ((NULL == str) || ('(' != str[0]) ||
+      (str[(slen = strlen (str)) - 1] != ')'))
     return str;
   memmove (str, &str[1], slen - 2);
   str[slen - 2] = '\0';
@@ -910,7 +932,8 @@ remove_parentheses (char *str)
 static int
 has_epsilon (const char *str)
 {
-  return  (NULL != str) && ('(' == str[0]) && ('|' == str[1]) && (')' == str[strlen(str) - 1]);
+  return (NULL != str) && ('(' == str[0]) && ('|' == str[1]) &&
+      (')' == str[strlen (str) - 1]);
 }
 
 
@@ -931,28 +954,28 @@ remove_epsilon (const char *str)
 
   if (NULL == str)
     return NULL;
-  if ( ('(' == str[0]) && ('|' == str[1]) )
+  if (('(' == str[0]) && ('|' == str[1]))
   {
     len = strlen (str);
-    if (')' == str[len-1])    
+    if (')' == str[len - 1])
       return GNUNET_strndup (&str[2], len - 3);
   }
   return GNUNET_strdup (str);
 }
 
-/** 
+/**
  * Compare 'str1', starting from position 'k',  with whole 'str2'
- * 
+ *
  * @param str1 first string to compare, starting from position 'k'
  * @param str2 second string for comparison
  * @param k starting position in 'str1'
- * 
+ *
  * @return -1 if any of the strings is NULL, 0 if equal, non 0 otherwise
  */
 static int
 strkcmp (const char *str1, const char *str2, size_t k)
 {
-  if ( (NULL == str1) || (NULL == str2) || (strlen(str1) < k) )
+  if ((NULL == str1) || (NULL == str2) || (strlen (str1) < k))
     return -1;
   return strcmp (&str1[k], str2);
 }
@@ -962,20 +985,23 @@ strkcmp (const char *str1, const char *str2, size_t k)
  * Compare two strings for equality. If either is NULL (or if both are
  * NULL), they are not equal.
  *
- * @return 0 if the strings are the same, 1 or -1 if not
+ * @param str1 first string for comparison.
+ * @param str2 second string for comparison.
+ *
+ * @return  0 if the strings are the same, 1 or -1 if not
  */
 static int
 nullstrcmp (const char *str1, const char *str2)
 {
-  if ( (NULL == str1) || (NULL == str2) )
+  if ((NULL == str1) || (NULL == str2))
     return -1;
   return strcmp (str1, str2);
 }
 
-/** 
+/**
  * Helper function used as 'action' in 'automaton_traverse' function to create
  * the depth-first numbering of the states.
- * 
+ *
  * @param cls states array.
  * @param count current state counter.
  * @param s current state.
@@ -1036,37 +1062,37 @@ automaton_create_proofs (struct GNUNET_REGEX_Automaton *a)
   /* Compute regular expressions of length "1" between each pair of states */
   for (i = 0; i < n; i++)
   {
-    for (j=0;j<n;j++)
+    for (j = 0; j < n; j++)
     {
       R_cur[i][j] = NULL;
       R_last[i][j] = NULL;
     }
     for (t = states[i]->transitions_head; NULL != t; t = t->next)
     {
-      j = t->to_state->proof_id;      
+      j = t->to_state->proof_id;
       if (NULL == R_last[i][j])
-	GNUNET_asprintf (&R_last[i][j], "%c", t->label);
+        GNUNET_asprintf (&R_last[i][j], "%c", t->label);
       else
-	{
-	  temp_a = R_last[i][j];
-	  GNUNET_asprintf (&R_last[i][j], "%s|%c", R_last[i][j], t->label);
-	  GNUNET_free (temp_a);
-	}
+      {
+        temp_a = R_last[i][j];
+        GNUNET_asprintf (&R_last[i][j], "%s|%c", R_last[i][j], t->label);
+        GNUNET_free (temp_a);
+      }
       if (GNUNET_YES == needs_parentheses (R_last[i][j]))
-        {
-	  temp_a = R_last[i][j];
-	  GNUNET_asprintf (&R_last[i][j], "(%s)", R_last[i][j]);
-	  GNUNET_free (temp_a);
-	}
+      {
+        temp_a = R_last[i][j];
+        GNUNET_asprintf (&R_last[i][j], "(%s)", R_last[i][j]);
+        GNUNET_free (temp_a);
+      }
     }
     if (NULL == R_last[i][i])
       GNUNET_asprintf (&R_last[i][i], "");
     else
-      {
-	temp_a = R_last[i][i];
-	GNUNET_asprintf (&R_last[i][i], "(|%s)", R_last[i][i]);
-	GNUNET_free (temp_a);
-      }  
+    {
+      temp_a = R_last[i][i];
+      GNUNET_asprintf (&R_last[i][i], "(|%s)", R_last[i][i]);
+      GNUNET_free (temp_a);
+    }
   }
 
 
@@ -1086,12 +1112,12 @@ automaton_create_proofs (struct GNUNET_REGEX_Automaton *a)
         R_cur_r = NULL;
         R_cur_l = NULL;
 
-	// cache results from strcmp, we might need these many times
-	ij_kj_cmp = nullstrcmp (R_last[i][j], R_last[k][j]);
-	ij_ik_cmp = nullstrcmp (R_last[i][j], R_last[i][k]);
-	ik_kk_cmp = nullstrcmp (R_last[i][k], R_last[k][k]);
-	ik_kj_cmp = nullstrcmp (R_last[i][k], R_last[k][j]);
-	kk_kj_cmp = nullstrcmp (R_last[k][k], R_last[k][j]);
+        // cache results from strcmp, we might need these many times
+        ij_kj_cmp = nullstrcmp (R_last[i][j], R_last[k][j]);
+        ij_ik_cmp = nullstrcmp (R_last[i][j], R_last[i][k]);
+        ik_kk_cmp = nullstrcmp (R_last[i][k], R_last[k][k]);
+        ik_kj_cmp = nullstrcmp (R_last[i][k], R_last[k][j]);
+        kk_kj_cmp = nullstrcmp (R_last[k][k], R_last[k][j]);
 
         // $R^{(k)}_{ij} = R^{(k-1)}_{ij} | R^{(k-1)}_{ik} ( R^{(k-1)}_{kk})^* R^{(k-1)}_{kj}
         // With: R_cur[i][j] = R_cur_l | R_cur_r
@@ -1116,19 +1142,19 @@ automaton_create_proofs (struct GNUNET_REGEX_Automaton *a)
 
           // Assign R_temp_(ik|kk|kj) to R_last[][] and remove epsilon as well
           // as parentheses, so we can better compare the contents
-	  R_temp_ik = remove_parentheses (remove_epsilon (R_last[i][k]));
+          R_temp_ik = remove_parentheses (remove_epsilon (R_last[i][k]));
           R_temp_kk = remove_parentheses (remove_epsilon (R_last[k][k]));
           R_temp_kj = remove_parentheses (remove_epsilon (R_last[k][j]));
 
           clean_ik_kk_cmp = nullstrcmp (R_last[i][k], R_temp_kk);
           clean_kk_kj_cmp = nullstrcmp (R_temp_kk, R_last[k][j]);
-          
+
           // construct R_cur_l (and, if necessary R_cur_r)
           if (NULL != R_last[i][j])
           {
             // Assign R_temp_ij to R_last[i][j] and remove epsilon as well
             // as parentheses, so we can better compare the contents
-	    R_temp_ij = remove_parentheses (remove_epsilon (R_last[i][j]));
+            R_temp_ij = remove_parentheses (remove_epsilon (R_last[i][j]));
 
             if (0 == strcmp (R_temp_ij, R_temp_ik) &&
                 0 == strcmp (R_temp_ik, R_temp_kk) &&
@@ -1218,7 +1244,8 @@ automaton_create_proofs (struct GNUNET_REGEX_Automaton *a)
             else
             {
               /* GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "NO SIMPLIFICATION\n"); */
-	      temp_a = (NULL == R_last[i][j]) ? NULL : GNUNET_strdup (R_last[i][j]);
+              temp_a =
+                  (NULL == R_last[i][j]) ? NULL : GNUNET_strdup (R_last[i][j]);
               temp_a = remove_parentheses (temp_a);
               R_cur_l = temp_a;
             }
@@ -1431,8 +1458,8 @@ automaton_create_proofs (struct GNUNET_REGEX_Automaton *a)
       for (j = 0; j < n; j++)
       {
         GNUNET_free_non_null (R_last[i][j]);
-	R_last[i][j] = R_cur[i][j];
-	R_cur[i][j] = NULL;       
+        R_last[i][j] = R_cur[i][j];
+        R_cur[i][j] = NULL;
       }
     }
   }
@@ -1466,7 +1493,7 @@ automaton_create_proofs (struct GNUNET_REGEX_Automaton *a)
       }
     }
   }
-  a->computed_regex = complete_regex;
+  a->canonical_regex = complete_regex;
 
   GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
               "---------------------------------------------\n");
@@ -2508,7 +2535,7 @@ GNUNET_REGEX_automaton_destroy (struct GNUNET_REGEX_Automaton *a)
     return;
 
   GNUNET_free_non_null (a->regex);
-  GNUNET_free_non_null (a->computed_regex);
+  GNUNET_free_non_null (a->canonical_regex);
 
   for (s = a->states_head; NULL != s;)
   {
@@ -2773,20 +2800,25 @@ GNUNET_REGEX_eval (struct GNUNET_REGEX_Automaton *a, const char *string)
   return result;
 }
 
+
 /**
- * Get the computed regex of the given automaton.
+ * Get the canonical regex of the given automaton.
  * When constructing the automaton a proof is computed for each state,
  * consisting of the regular expression leading to this state. A complete
  * regex for the automaton can be computed by combining these proofs.
- * As of now this computed regex is only useful for testing.
+ * As of now this function is only useful for testing.
+ *
+ * @param a automaton for which the canonical regex should be returned.
+ *
+ * @return
  */
 const char *
-GNUNET_REGEX_get_computed_regex (struct GNUNET_REGEX_Automaton *a)
+GNUNET_REGEX_get_canonical_regex (struct GNUNET_REGEX_Automaton *a)
 {
   if (NULL == a)
     return NULL;
 
-  return a->computed_regex;
+  return a->canonical_regex;
 }
 
 /**