# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1376036642 -7200
# Node ID 0a70e0d369499848b15b8806f2f9d89c36f5a589
# Parent  c7d7e4eeb76be12953845f4186acac2d1f4a2303
finished documentation of UcxProperties

diff -r c7d7e4eeb76b -r 0a70e0d36949 ucx/properties.h
--- a/ucx/properties.h	Wed Aug 07 09:40:46 2013 +0200
+++ b/ucx/properties.h	Fri Aug 09 10:24:02 2013 +0200
@@ -44,39 +44,128 @@
 extern "C" {
 #endif
 
+/**
+ * UcxProperties object for parsing properties data.
+ * Most of the fields are for internal use only. You may configure the
+ * properties parser, e.g. by changing the used delimiter or specifying 
+ * up to three different characters that shall introduce comments.
+ */
 typedef struct {
+    /**
+     * Input buffer (don't set manually).
+     * Automatically set by calls to ucx_properties_fill().
+     */
     char   *buffer;
+    /**
+     * Length of the input buffer (don't set manually).
+     * Automatically set by calls to ucx_properties_fill().
+     */
     size_t buflen;
+    /**
+     * Current buffer position (don't set manually).
+     * Used by ucx_properties_next().
+     */
     size_t pos;
+    /**
+     * Internal temporary buffer (don't set manually).
+     * Used by ucx_properties_next().
+     */
     char   *tmp;
+    /**
+     * Internal temporary buffer length (don't set manually).
+     * Used by ucx_properties_next().
+     */
     size_t tmplen;
+    /**
+     * Internal temporary buffer capacity (don't set manually).
+     * Used by ucx_properties_next().
+     */
     size_t tmpcap;
+    /**
+     * Parser error code.
+     * This is always 0 on success and a nonzero value on syntax errors.
+     * The value is set by ucx_properties_next().
+     */
     int    error;
+    /**
+     * The delimiter that shall be used.
+     * This is '=' by default.
+     */
     char   delimiter;
+    /**
+     * The first comment character.
+     * This is '#' by default.
+     */
     char   comment1;
+    /**
+     * The second comment character.
+     * This is not set by default.
+     */
     char   comment2;
+    /**
+     * The third comment character.
+     * This is not set by default.
+     */
     char   comment3;
 } UcxProperties;
 
 
 /**
  * Constructs a new UcxProperties object.
- * @return A pointer to the new UcxProperties object.
+ * @return a pointer to the new UcxProperties object
  */
 UcxProperties *ucx_properties_new();
 /**
  * Destroys an UcxProperties object.
- * @param prop The UcxProperties object to destroy.
+ * @param prop the UcxProperties object to destroy
  */
 void ucx_properties_free(UcxProperties *prop);
 /**
- * Refills the input buffer.
- * @param prop The UcxProperties object.
- * @param buf A pointer to the new buffer.
- * @param len The payload length of the buffer.
+ * Sets the input buffer for the properties parser.
+ * 
+ * After calling this function, you may parse the data by calling
+ * ucx_properties_next() until it returns 0. The function ucx_properties2map()
+ * is a convenience function that performs these successive calls of
+ * ucx_properties_next() within a while loop and puts the properties to a map.
+ * 
+ * 
+ * @param prop the UcxProperties object
+ * @param buf a pointer to the new buffer
+ * @param len the payload length of the buffer
+ * @see ucx_properties_next()
+ * @see ucx_properties2map()
  */
 void ucx_properties_fill(UcxProperties *prop, char *buf, size_t len);
+/**
+ * Retrieves the next key/value-pair.
+ * 
+ * This function returns a nonzero value as long as there are key/value-pairs
+ * found. If no more key/value-pairs are found, you may refill the input buffer
+ * with ucx_properties_fill().
+ * 
+ * <b>Attention:</b> the sstr_t.ptr pointers of the output parameters point to
+ * memory within the input buffer of the parser and will get invalid some time.
+ * If you want long term copies of the key/value-pairs, use sstrdup() after
+ * calling this function.
+ * 
+ * @param prop the UcxProperties object
+ * @param name a pointer to the sstr_t that shall contain the property name
+ * @param value a pointer to the sstr_t that shall contain the property value
+ * @return Nonzero, if a key/value-pair was successfully retrieved
+ * @see ucx_properties_fill()
+ */
 int ucx_properties_next(UcxProperties *prop, sstr_t *name, sstr_t *value);
+/**
+ * Retrieves all available key/value-pairs and puts them into an UcxMap.
+ * 
+ * This is done by successive calls to ucx_properties_next() until no more
+ * key/value-pairs can be retrieved. 
+ * 
+ * @param prop the UcxProperties object
+ * @param map the target map
+ * @return The UcxProperties.error code (i.e. 0 on success).
+ * @see ucx_properties_fill()
+ */
 int ucx_properties2map(UcxProperties *prop, UcxMap *map);
 
 /**
@@ -87,8 +176,8 @@
  * 
  * An UcxProperties object is implicitly created and destroyed.
  * 
- * @param map The map object to write the key/value-pairs to.
- * @param file The <code>FILE*</code> stream to read from.
+ * @param map the map object to write the key/value-pairs to
+ * @param file the <code>FILE*</code> stream to read from
  * @return 0 on success, or a non-zero value on error
  * 
  * @see ucx_properties_fill()
@@ -102,8 +191,8 @@
  * 
  * <code>[key] = [value]\\n</code>
  * 
- * @param map The map to store.
- * @param file The <code>FILE*</code> stream to write to.
+ * @param map the map to store
+ * @param file the <code>FILE*</code> stream to write to
  * @return 0 on success, or a non-zero value on error
  */
 int ucx_properties_store(UcxMap *map, FILE *file);