Index: ossp-pkg/val/val.pod
RCS File: /v/ossp/cvs/ossp-pkg/val/val.pod,v
rcsdiff -q -kk '-r1.4' '-r1.5' -u '/v/ossp/cvs/ossp-pkg/val/val.pod,v' 2>/dev/null
--- val.pod	2002/01/16 20:47:56	1.4
+++ val.pod	2002/01/17 09:22:18	1.5
@@ -83,19 +83,34 @@
 It allows one to access C variables through name strings, although
 the C language does neither provide such a dedicated facility nor an
 evaluation construct (which could be used to implement such a facility
-easily). In general, it is interesting whenevery you need access to C
+easily). In general, it is interesting whenever you need access to C
 variable symbols without having to know the actual address/reference.
 The typical use cases are in combination with flexible configuration
 parsing and supporting loosly-coupled DSO-based module architectures.
 
+=head1 STRUCTURED NAMES
+
+Whenever the APIs calls for a name it supports structured names where elements
+are separated by a dot. It is assumed that the leading elements are references
+to other C<val_t> structures and only the very last element is a reference to
+an actual variable.
+
 =head1 API CONSTANTS
 
 =over 4
 
 =item C<VAL_MAXNAME>
 
+The maximum length of a variable name. For structured variables this includes
+the concatenation of all elements within a path and their separating dots.
+
 =item C<VAL_TYPE_>I<ID>
 
+Type of value when registering a variable using B<val_reg>() or querying for
+the type using B<val_query>(). Most are self-explanatory, C<VAL_TYPE_VAL> is
+used to mount a C<val_t> structure into an existing C<val_t> structure to
+support structured names.
+
 C<VAL_TYPE_VAL>,
 C<VAL_TYPE_PTR>,
 C<VAL_TYPE_CHAR>,
@@ -107,6 +122,12 @@
 
 =item C<VAL_OK>, C<VAL_ERR_>I<ID>
 
+Return codes for every API function. Signals success, invalid argument passed
+to function, bad usage of a function, memoryusage reached C<VAL_MAXNAME>
+limit, error in internal hash function to be examined through C<errno>,
+internal error in storage as result from structure corruption, or system
+errors including out of memory.
+
 C<VAL_ERR_ARG>,
 C<VAL_ERR_USE>,
 C<VAL_ERR_MEM>,
@@ -122,10 +143,18 @@
 
 =item C<val_t>
 
+Handle created by B<val_create>() and passed to all other functions to reference
+the the same group of variables.
+
 =item C<val_cb_t>
 
+Callback to be used B<var_apply>().
+
 =item C<val_rc_t>
 
+Code returned by every function. See C<API_CONSTANTS> C<VAL_OK> and
+C<VAL_ERR_>I<ID>.
+
 =back
 
 =head1 API FUNCTIONS
@@ -134,22 +163,69 @@
 
 =item val_rc_t B<val_create>(val_t **I<pval>);
 
+Creates an I<val> and updates the given pointer to reference it.
+
 =item val_rc_t B<val_destroy>(val_t *I<val>);
 
+Destroys an I<val>, freeing up memory.
+
 =item val_rc_t B<val_reg>(val_t *I<val>, const char *I<name>, int I<type>, const char *I<desc>, void *I<storage>);
 
+Registers a variable I<name> using I<type> in I<val>. An optional description
+or NULL can be passed through I<desc> which can be queried through
+B<val_query>() and is also passed to the callback of B<val_apply>(). The value
+that belongs to the given I<name> is expected to be found at I<storage>.
+Passing NULL as I<storage> will create an inline data store in I<val> so it
+can only be access through B<val_get>(), B<val_set>() or after the actual
+storage address was queried using B<val_query>().
+
 =item val_rc_t B<val_query>(val_t *I<val>, const char *I<name>, int *I<ptype>, char **I<pdesc>, void **I<pstorage>);
 
+Queries a variable I<name> in I<val> and returns it's type, description and
+storage address. All of I<ptype>, I<pdesc> and I<pstorage> are optional and
+NULL can be passed in if this information is not needed. Passing NULL to all
+query result pointers just checks for existence of I<name>.
+
 =item val_rc_t B<val_set>(val_t *I<val>, const char *I<name>, ...);
 
+Sets the value of variable I<name> in I<val> to the data passed in as vararg.
+Unless the actual storage address was queried using B<val_query>() this is
+mandatory for inline data. Usually not the value but a pointer to it is stored
+to the value can be modified without notice to the library.
+
 =item val_rc_t B<val_get>(val_t *I<val>, const char *I<name>, ...);
 
+Gets the value of variable I<name> in I<val> and stores it whereever the
+passed vararg points to.
+
 =item val_rc_t B<val_vset>(val_t *I<val>, const char *I<name>, va_list I<ap>);
 
+Like B<val_set>() but takes a C<va_list> as input to allow recursive
+execution. Acutally, B<val_set>() ist just a wrapper around
+B<val_vset>().
+
 =item val_rc_t B<val_vget>(val_t *I<val>, const char *I<name>, va_list I<ap>);
 
+Like B<val_get>() but takes a C<va_list> as input to allow recursive
+execution. Acutally, B<val_get>() ist just a wrapper around
+B<val_vget>().
+
 =item val_rc_t B<val_apply>(val_t *I<val>, const char *I<name>, int I<depth>, val_cb_t I<cb>, void *I<ctx>);
 
+Iterates through all elements of I<val>, starting with I<name> which can be
+either a data store or I<val> reference, down to a given recursion I<depth>.
+When I<name> is set to the empty string the search starts immediately at
+I<val>.  For every element, the callback I<cb>() is executed and a context
+I<ctx> is passed to it along with other information described below.
+
+=item val_rc_t (*)(void *I<ctx>, const char *I<name>, int I<type>, const char *I<desc>, void *I<data>)
+
+Callback executed by B<val_apply>() for each element being processed. The
+context I<ctx> input to B<val_apply>() is passed to the callback verbatim. The
+I<name> is the structured name relative to the I<val> passed to
+B<val_apply>(), I<type> signals the type of value I<data> points to and
+I<desc> is a text which was optionally passed to B<val_reg>().
+
 =back
 
 =head1 SEE ALSO