# HG changeset patch
# User Matti Hamalainen <ccr@tnsp.org>
# Date 1579953961 -7200
# Node ID ae601363fdad2137d8f25ff9573e09fadb52b582
# Parent  1092eb33bd5903cdc30535b64b8c04dc3c86afb2
Doxygenization.

diff -r 1092eb33bd59 -r ae601363fdad th_config.c
--- a/th_config.c	Sat Jan 25 13:37:01 2020 +0200
+++ b/th_config.c	Sat Jan 25 14:06:01 2020 +0200
@@ -173,6 +173,7 @@
 
 /* Read a given file into configuration structure and variables
  */
+/// @cond
 enum
 {
     PM_EOF,
@@ -198,6 +199,8 @@
         prevMode, nextMode, parseMode;
 } th_cfgparserctx_t;
 
+/// @endcond
+
 
 static void th_cfg_set_parsemode(th_cfgparserctx_t *ctx, const int mode)
 {
diff -r 1092eb33bd59 -r ae601363fdad th_regex.c
--- a/th_regex.c	Sat Jan 25 13:37:01 2020 +0200
+++ b/th_regex.c	Sat Jan 25 14:06:01 2020 +0200
@@ -5,7 +5,6 @@
  *
  * Please read file 'COPYING' for information on license and distribution.
  */
-#include "th_util.h"
 #include "th_regex.h"
 
 
@@ -24,6 +23,7 @@
 #endif
 
 
+/// @cond
 enum
 {
     TH_RE_MATCH_ONCE,
@@ -96,13 +96,6 @@
 } th_regex_node_t;
 
 
-struct th_regex_t
-{
-    size_t nnodes, nodessize;
-    th_regex_node_t *nodes;
-};
-
-
 typedef struct
 {
     const th_regex_char_t *pattern;
@@ -119,6 +112,15 @@
 } th_regex_parse_ctx_t;
 
 
+struct th_regex_t
+{
+    size_t nnodes, nodessize;
+    th_regex_node_t *nodes;
+};
+
+/// @endcond
+
+
 static void th_regex_node_init(th_regex_node_t *node)
 {
     memset(node, 0, sizeof(th_regex_node_t));
@@ -438,6 +440,15 @@
 }
 
 
+/**
+ * Parse given regular expression @p pattern string into compiled/tokenized
+ * form as @c th_regex_t structures. Returns @c THERR_OK if successful,
+ * or other @c THERR_* return value if not. In either case, the @p pexpr
+ * may have been allocated and must be freed via th_regex_free().
+ * @param[in,out] pexpr pointer to a pointer of @c th_regex_t structures to be 
+ * @param[in] pattern regular expression pattern string
+ * @returns @c THERR_* return value indicating success or failure
+ */
 int th_regex_compile(th_regex_t **pexpr, const th_regex_char_t *pattern)
 {
     int res = THERR_OK;
@@ -704,6 +715,13 @@
 }
 
 
+/**
+ * Deallocate the given regular expression structure @p expr.
+ * All associated data will be freed, though pointers may not
+ * be NULLed.
+ *
+ * @param[in] expr structure to be deallocated
+ */
 void th_regex_free(th_regex_t *expr)
 {
     if (expr != NULL)
@@ -777,6 +795,15 @@
 }
 
 
+/**
+ * Print out the contents of given regular expression structure @p expr
+ * in "human-readable" format to specified @c th_ioctx context. Typically
+ * useful for debugging purposes only.
+ *
+ * @param[in,out] fh th_ioctx handle to be used for output, must be writable.
+ * @param[in] level starting whitespace indentation level
+ * @param[in] expr regular expression structure to be "dumped"
+ */
 void th_regex_dump(th_ioctx *fh, const int level, const th_regex_t *expr)
 {
     if (expr != NULL)
@@ -1028,6 +1055,20 @@
 }
 
 
+/**
+ * Match the specified string @p haystack against specified compiled
+ * regular expression @p expr and return results in optional variables
+ * @p pnmatches for number of matches and/or @p pmatches @c th_regex_match_t
+ * structures for matching sequences information. If @p pmatches is used,
+ * the resulting linked list should be eventually freed via th_regex_free_matches().
+ *
+ * @param[in] expr regular expression structure to be matched
+ * @param[in] haystack string to be matched against
+ * @param[out] pnmatches pointer to variable to be set to number of found matches, or @c NULL if the information is not desired
+ * @param[out] pmatches pointer to a pointer of @c th_regex_match_t structures, or @c NULL if the information is not desired
+ * @param[in] maxmatches maximum number of matches until bailing out, or @c 0 if no limit
+ * @param[in] flags additional flags, see @c TH_REF_*
+ */
 int th_regex_match(const th_regex_t *expr, const th_regex_char_t *haystack,
     size_t *pnmatches, th_regex_match_t **pmatches, const size_t maxmatches,
     const int flags)
@@ -1102,6 +1143,13 @@
 }
 
 
+/**
+ * Deallocate the given set of @c th_regex_match_t
+ * linked list structures pointed by @p matches.
+ * All associated data will be freed.
+ *
+ * @param[in] matches structure to be deallocated
+ */
 void th_regex_free_matches(th_regex_match_t *matches)
 {
     th_llist_free_func_node((th_llist_t *) matches,
diff -r 1092eb33bd59 -r ae601363fdad th_regex.h
--- a/th_regex.h	Sat Jan 25 13:37:01 2020 +0200
+++ b/th_regex.h	Sat Jan 25 14:06:01 2020 +0200
@@ -5,10 +5,11 @@
  *
  * Please read file 'COPYING' for information on license and distribution.
  */
+/// @file
+/// @brief Simple regular expression matching functionality
 #ifndef TH_REGEX_H
 #define TH_REGEX_H
 
-#include "th_types.h"
 #include "th_datastruct.h"
 #include "th_ioctx.h"
 
@@ -22,20 +23,29 @@
 // Definitions
 //
 
-// Character type
+/** @brief th_regex_char_t
+ * Character type used by th_regex module.
+ */
 typedef char th_regex_char_t;
 
 
-// Structure containing the compiled regular expression
+/** @struct th_regex_t
+ * Structure containing the tokenized / compiled regular expression.
+ */
 struct th_regex_t;
 typedef struct th_regex_t th_regex_t;
 
 
-// Linked list structure for returned match sequences
+/** @brief
+ * Linked list structure containing the information for matched
+ * sequences returned by th_regex_match().
+ */
 typedef struct
 {
-    th_llist_t node;
-    size_t start, len;
+    th_llist_t node;    ///< Internal linked list data
+
+    size_t start;       ///< Start offset of the match sequence in @p haystack in @c th_regex_char_t units.
+    size_t len;         ///< Length of the match sequence in @p haystack in @c th_regex_char_t units.
 } th_regex_match_t;