Index: ossp-pkg/l2/TODO
RCS File: /v/ossp/cvs/ossp-pkg/l2/TODO,v
rcsdiff -q -kk '-r1.55' '-r1.56' -u '/v/ossp/cvs/ossp-pkg/l2/TODO,v' 2>/dev/null
--- TODO	2002/05/28 12:19:47	1.55
+++ TODO	2002/07/25 07:50:27	1.56
@@ -1,7 +1,46 @@
 OSSP L2 TODO
 ============
 
-New Idea as thl discussed with rse a few minutes ago
+Structure of channels and documentation [thl]. It should be possible to
+drag the documentation out of a channel's source code. Everything else
+is error prone and a documentation nightmare. Currently, most (noop and
+null doesn't) channels have a code segment that looks like
+
+    /* feed and call generic parameter parsing engine */
+    L2_PARAM_SET(pa[0], size,       INT, &cfg->bufsize);
+    L2_PARAM_SET(pa[1], interval,   INT, &cfg->bufinterval);
+    L2_PARAM_SET(pa[2], levelflush, INT, &cfg->levelflush);
+    L2_PARAM_END(pa[3]);
+    l2_channel_env(ch, &env);
+
+I recommend the L2_PARAM_SET macro should be modified to
+
+- set the default value of each paramater, if any exists
+- force the internal structure name to follow the revealed name
+- declare a channel to be a filter or output
+- declare parameters optional or mandatory
+
+Also i recommend an organizational enforcement of putting the
+channel description before such a code segment and a short description
+(i.e. unit, 0=deactivate) of each parameter/value just behind the macro.
+This could change the example above to look something like:
+
+    /*<man description=channel, type=filter>
+     * The buffer channel buffers messages poured in from upper channels.
+     * It flushes the messages down to the lower channels when the buffered
+     * space exceeds the buffer size, when a given time interval is reached
+     * (0 disables this feature) or when a newly arrived message has a
+     * level that matches the levelflush mask.
+     *
+    /* feed and call generic parameter parsing engine */
+    L2_PARAM_SET(pa[0], size,       INT, 4096); /* o: bytes */
+    L2_PARAM_SET(pa[1], interval,   INT, 0   ); /* o: sec, 0=disable */
+    L2_PARAM_SET(pa[2], levelflush, INT, 0   ); /* o: levelmask */
+    L2_PARAM_END(pa[3]);
+    l2_channel_env(ch, &env);
+    /*</man>*/
+
+Neh idea as thl discussed with rse a few minutes ago
 
 - l2 should calculate the global logging mask automatically based on
   the OR'ing the masks of all output channels. This should increase