Index: ossp-pkg/var/var.h
RCS File: /v/ossp/cvs/ossp-pkg/var/var.h,v
rcsdiff -q -kk '-r1.12' '-r1.13' -u '/v/ossp/cvs/ossp-pkg/var/var.h,v' 2>/dev/null
--- var.h	2001/11/19 16:07:15	1.12
+++ var.h	2001/11/19 16:09:44	1.13
@@ -74,64 +74,19 @@
     VAR_OK = 0
 } var_rc_t;
 
-/*
-   Expand the following named characters to their binary
-   representation:
-
-       \t          tab
-       \n          newline
-       \r          return
-       \033        octal char
-       \x1B        hex char
-       \x{263a}    wide hex char
-
-  Any other character quoted by a backslash is copied verbatim.
-*/
+/* Expand quoted pairs to their binary representation. */
 
 var_rc_t var_unescape(const char *src, size_t len, char *dst,
     int unescape_all);
 
-/*
-   The callback will be called by variable_expand(), providing the
-   following parameters:
-
-        context         - passed through from variable_expand()'s
-                          parameters
-        varname         - pointer to the name of the variable to
-                          expand
-        name_len        - length of the string starting at varname
-        data            - location, where the callback should store
-                          the pointer to the contents of the looked-up
-                          variable
-        data_len        - location, where the callback should store
-                          the length of the data
-        malloced_buffer - location, where the callback should store
-                          either TRUE or FALSE, telling the framework
-                          whether the buffer must be free(3)ed.
-
-   The return code is interpreted as follows:
-       >0               - OK
-        0               - undefined variable
-       <0 - error
-*/
+/* Prototype for the lookup callback used in var_expand(). */
 
 typedef int (*var_cb_t) (void *context,
     const char *varname, size_t name_len,
     const char **data, size_t *data_len,
-//FIXME THL: description "malloced_buffer" vs. prototype "size_t *buffer_size"
     size_t *buffer_size);
 
-/*
-   This structure configures the parser's specials. I think, the fields
-   are pretty self-explanatory. The only one worth mentioning is
-   force_expand, which is a boolean. If set to TRUE, variable_expand()
-   will fail with an error if the lookup callback returns "undefined
-   variable". If set to FALSE, variable_expand() will copy the
-   expression that failed verbatimly to the output so that another pass
-   may expand it.
-
-   The comments after each field show the default configuration.
-*/
+/* Configure the var_expand() parser's tokens. */
 
 typedef struct {
     char varinit;        /* '$' */
@@ -139,24 +94,17 @@
     char enddelim;       /* '}' */
     char escape;         /* '\' */
     char *namechars;     /* 'a-zA-Z0-9_' */
-//FIXME THL: should we support namechars with different first char, i.e. [a-z][a-z0-9]*
 } var_config_t;
 extern const var_config_t var_config_default;
 
-/*
-   variable_expand() will parse the contents of input for variable
-   expressions and expand them using the provided lookup callback. The
-   pointer to the resulting buffer is stored in result, its length in
-   result_len. The buffer is always terminated by a '\0' byte, which is
-   not included in the result_len count. The buffer must be free(3)ed
-   by the caller.
-*/
+/* Expand variable expressions in a text buffer. */
 
 var_rc_t var_expand(const char *input, size_t input_len,
     char **result, size_t *result_len,
     var_cb_t lookup, void *lookup_context,
     const var_config_t *config, int force_expand);
-//FIXME THL: "force_expand" used here but described and unused above in "var_config_t"
+
+/* Map an error code to a text message. */
 
 const char* var_strerror(var_rc_t rc);