From 9785ea02e3b672cfb2064bd89a4c6b35b042d487 Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Tue, 27 May 2025 22:16:04 +0200 Subject: [PATCH] Revamp documentation of filter.c --- filter.c | 43 +++++++++++++++++++++++++------------------ 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/filter.c b/filter.c index a08bea51..378f6b15 100644 --- a/filter.c +++ b/filter.c @@ -1,6 +1,12 @@ /* Copyright (C) 2005 Andre Noll , 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 @@ -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[]) { -- 2.39.5