Revamp documentation of filter.c

diff --git a/filter.c b/filter.c
index a08bea51581b65d782980352ff33f8dadd018f69..378f6b15d51ce1abcde654d34d5818f0bc978c17 100644 (file)
--- a/filter.c
+++ b/filter.c
@@ -1,6 +1,12 @@
 /* Copyright (C) 2005 Andre Noll <maan@tuebingen.mpg.de>, see file COPYING. */
 
-/** \file filter.c The stand-alone filter program. */
+/** \file filter.c The stand-alone filter program.
+ *
+ * This file defines only one non-static function, main(), the entry function
+ * of para_filter(1). All filters are linked into the para_filter() executable
+ * as well. The buffer tree code and the paraslash scheduler are employed
+ * to implement single-threaded filter chaining.
+ */
 
 #include <lopsub.h>
 
@@ -18,7 +24,7 @@
 #include "error.h"
 #include "fd.h"
 
-/** Array of error strings. */
+/** \cond doxygen_ignore */
 DEFINE_PARA_ERRLIST;
 static struct lls_parse_result *lpr; /* command line options */
 
@@ -28,26 +34,21 @@ static struct lls_parse_result *lpr; /* command line options */
 #define OPT_GIVEN(_name) (lls_opt_given(OPT_RESULT(_name)))
 #define OPT_UINT32_VAL(_name) (lls_uint32_val(0, OPT_RESULT(_name)))
 
-/**
- * Dummy version which only contains NULL pointers.
- *
- * This is used by the amp filter which first tries to obtain the amplification
- * value from an element in this array.
+/*
+ * This array contains only NULL pointers. It is needed by the amp filter
+ * which first tries to obtain the amplification value from an element in
+ * this array.
  */
 const char *stat_item_values[NUM_STAT_ITEMS] = {NULL};
 
-/** The task that reads from stdin. */
 static struct stdin_task stdin_task_struct;
-/** pointer to the stdin task. */
 static struct stdin_task *sit = &stdin_task_struct;
-
-/** The task that writes converted data to stdout. */
 static struct stdout_task stdout_task_struct;
-/** Pointer to the stdout task. */
 static struct stdout_task *sot = &stdout_task_struct;
 
 static int loglevel;
 INIT_STDERR_LOGGING(loglevel);
+/** \endcond doxygen_ignore */
 
 static void handle_help_flag(void)
 {
@@ -86,14 +87,20 @@ static int parse_config(void)
 /**
  * The main function of para_filter.
  *
- * Para_filter reads data from stdin, converts it by using a chain
- * of filters (specified on the command line) and writes the resulting
- * data to stdout.
+ * Para_filter reads data from stdin, converts it through a chain of filters
+ * and writes the resulting data to stdout.
+ *
+ * We define one task per given filter option, plus two additional tasks for
+ * stdin and stdout. The buffer tree nodes of the filter tasks are chained
+ * together and connected to the stdin and stdout buffer tree nodes much
+ * like a Unix pipe, but without creating additional processes or threads.
+ *
+ * \param argc Command line options are parsed via the lopsub library.
  *
- * \param argc Number of command line options.
- * \param argv Vector of arguments.
+ * \param argv Options are defined in the lopsub suite file. Each filter is
+ * realized as a lopsub "subcommand".
  *
- * \return \a EXIT_SUCCESS on success, EXIT_FAILURE on errors.
+ * \return EXIT_SUCCESS on success, EXIT_FAILURE on errors.
  */
 int main(int argc, char *argv[])
 {