Index: ossp-pkg/val/val.pod
RCS File: /v/ossp/cvs/ossp-pkg/val/val.pod,v
rcsdiff -q -kk '-r1.8' '-r1.9' -u '/v/ossp/cvs/ossp-pkg/val/val.pod,v' 2>/dev/null
--- val.pod	2002/01/17 13:01:58	1.8
+++ val.pod	2002/01/17 13:26:31	1.9
@@ -84,10 +84,12 @@
 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 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.
+easily). 
+
+In general, this is used for accessing C variables without having to
+know the actual symbol/address/reference. The typical use cases are
+in combination with flexible configuration parsing and supporting
+loosly-coupled DSO-based module architectures.
 
 =head1 STRUCTURED NAMES
 
@@ -107,33 +109,27 @@
 
 =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>,
-C<VAL_TYPE_SHORT>,
-C<VAL_TYPE_INT>,
-C<VAL_TYPE_LONG>,
-C<VAL_TYPE_FLOAT>,
-C<VAL_TYPE_DOUBLE>
+Type of value when registering a variable using B<val_reg>() or querying
+for the type using B<val_query>(). Most are self-explanatory because
+directly correspond to the basic C data types. C<VAL_TYPE_VAL> is used
+to mount a C<val_t> structure into an existing C<val_t> structure to
+support structured names (see example section for details).
+
+The following particular types exist: C<VAL_TYPE_VAL>, C<VAL_TYPE_PTR>,
+C<VAL_TYPE_CHAR>, C<VAL_TYPE_SHORT>, C<VAL_TYPE_INT>, C<VAL_TYPE_LONG>,
+C<VAL_TYPE_FLOAT>, C<VAL_TYPE_DOUBLE>
 
 =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>,
-C<VAL_ERR_HSH>,
-C<VAL_ERR_INT>,
+Return codes (of type C<val_rc_t>) for every API function. Signals success
+(C<VAL_OK>), invalid argument passed to function, bad usage of a function,
+memory usage 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 to be examined
+through C<errno>.
+
+The following particular return codes exist: C<VAL_OK>, C<VAL_ERR_ARG>,
+C<VAL_ERR_USE>, C<VAL_ERR_MEM>, C<VAL_ERR_HSH>, C<VAL_ERR_INT>,
 C<VAL_ERR_SYS>.
 
 =back
@@ -144,16 +140,16 @@
 
 =item C<val_t>
 
-Handle created by B<val_create>() and passed to all other functions to reference
-the the same group of variables.
+Opaque handle data type created by B<val_create>() and passed to all
+other functions to reference the the same group of values.
 
 =item C<val_cb_t>
 
-Callback to be used B<var_apply>().
+Function data type for the callback to be used with B<var_apply>().
 
 =item C<val_rc_t>
 
-Code returned by every function. See C<API_CONSTANTS> C<VAL_OK> and
+Data type returned by every function. See B<API CONSTANTS> C<VAL_OK> and
 C<VAL_ERR_>I<ID>.
 
 =back
@@ -164,78 +160,78 @@
 
 =item val_rc_t B<val_create>(val_t **I<pval>);
 
-Creates an I<val> and updates the given pointer to reference it.
+Creates a new value structure 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.
+Destroys a I<val> structure.
 
 =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>().
+Registers a value under I<name> of type I<type> in I<val>. An optional
+description or C<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 C<NULL> as I<storage> will create
+an internal data storage 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_unreg>(val_t *I<val>, const char *I<name>);
 
-Unregisters a variable I<name> in I<val>.
+Unregisters the value under I<name> in I<val>.
 
 =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
+Queries a value I<name> in I<val> and returns its 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>.
+C<NULL> can be passed in if this information is not needed. Passing C<NULL> to
+all query result pointers just checks for existence of the value I<name> in
+I<val>.
 
 =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.
+Sets the value I<name> in I<val> to the data passed in as the variable
+argument (expected to be of the I<type> specified at B<val_reg>() time).
+Unless the actual storage address was queried using B<val_query>() this
+operation is mandatory for internally stored data. If external storage
+is used, not the value but a pointer to it is stored in the library, so
+the value is allowed to be 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.
+Gets the value I<name> in I<val> and stores it whereever the passed variable
+argument points to. The storage location is expected to be of the I<type>
+specified at B<val_reg>() time.
 
 =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>().
+Exactly like B<val_set>() but uses a C<va_list>.
 
 =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>().
+Exactly like B<val_get>() but uses a C<va_list>.
 
 =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>().
+Iterates over all values in I<val>, starting with I<name>, which can be
+either a data storage or I<val_t> reference, down to a given recursion
+I<depth>. If I<name> is set to the empty string the search starts
+immediately at I<val>. For every value, the callback I<cb>() is executed.
+The callback has to be a function with the following prototype:
+
+val_rc_t cb(void *I<ctx>, const char *I<name>, int I<type>, const char *I<desc>, void *I<storage>);
+
+The I<ctx> is the passed-through context I<ctx> of B<val_apply>().
+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<storage> points to
+and I<desc> is the text which was optionally passed to B<val_reg>().
 
 =back
 
 =head1 SEE ALSO
 
-OSSP var.
+B<OSSP var> (Variable Expansion Library)
 
 =head1 EXAMPLES
 
@@ -349,8 +345,8 @@
 
 =head1 AUTHORS
 
- Thomas Lotterer
- Ralf S. Engelschall
+ Thomas Lotterer     <thomas.lotterer@cw.com>
+ Ralf S. Engelschall <rse@engelschall.com>
 
 =cut