# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1375706317 -7200
# Node ID 633f15ce2ee45c338dfaca722a3a265bc8632dac
# Parent  61edec666928c2472b20017f77e6dedeb875e921
started documentation of UcxProperties + some fixes

diff -r 61edec666928 -r 633f15ce2ee4 ucx/properties.c
--- a/ucx/properties.c	Wed Jul 24 14:26:17 2013 +0200
+++ b/ucx/properties.c	Mon Aug 05 14:38:37 2013 +0200
@@ -210,8 +210,8 @@
             return 1;
         }
     }
-    if(parser->error) {
-        return 1;
+    if (parser->error) {
+        return parser->error;
     } else {
         return 0;
     }
@@ -219,17 +219,20 @@
 
 int ucx_properties_load(UcxMap *map, FILE *file) {
     UcxProperties *parser = ucx_properties_new();
-    if(!parser || !map || !file) {
+    if(!(parser && map && file)) {
         return 1;
     }
     
+    // buffer size is documented - change doc, when you change bufsize!
+    const size_t bufsize = 1024;
+    
     int error = 0;
     size_t r;
-    char buf[1024];
-    while((r = fread(buf, 1, 1024, file)) != 0) {
+    char buf[bufsize];
+    while((r = fread(buf, 1, bufsize, file)) != 0) {
         ucx_properties_fill(parser, buf, r);
-        if(ucx_properties2map(parser, map)) {
-            error = 1;
+        error = ucx_properties2map(parser, map);
+        if (error) {
             break;
         }
     }
@@ -253,7 +256,9 @@
         written += fwrite(value.ptr, 1, value.length, file);
         written += fwrite("\n", 1, 1, file);
 
-        if (written != k.len + value.length + 4) return 1;
+        if (written != k.len + value.length + 4) {
+            return 1;
+        }
     }
 
     return 0;
diff -r 61edec666928 -r 633f15ce2ee4 ucx/properties.h
--- a/ucx/properties.h	Wed Jul 24 14:26:17 2013 +0200
+++ b/ucx/properties.h	Mon Aug 05 14:38:37 2013 +0200
@@ -25,6 +25,14 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
+/**
+ * @file properties.h
+ * 
+ * Load / store utilities for properties files.
+ * 
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ */
 
 #ifndef UCX_PROPERTIES_H
 #define	UCX_PROPERTIES_H
@@ -51,13 +59,53 @@
 } UcxProperties;
 
 
+/**
+ * Constructs a new UcxProperties object.
+ * @return A pointer to the new UcxProperties object.
+ */
 UcxProperties *ucx_properties_new();
-void ucx_properties_free(UcxProperties *parser);
-void ucx_properties_fill(UcxProperties *parser, char *buf, size_t len);
-int ucx_properties_next(UcxProperties *parser, sstr_t *name, sstr_t *value);
-int ucx_properties2map(UcxProperties *parser, UcxMap *map);
+/**
+ * Destroys an UcxProperties object.
+ * @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.
+ */
+void ucx_properties_fill(UcxProperties *prop, char *buf, size_t len);
+int ucx_properties_next(UcxProperties *prop, sstr_t *name, sstr_t *value);
+int ucx_properties2map(UcxProperties *prop, UcxMap *map);
 
+/**
+ * Loads a properties file to an UcxMap.
+ * 
+ * This is a convenience function that reads chunks of 1 KB from an input
+ * stream until the end of the stream is reached.
+ * 
+ * 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.
+ * @return 0 on success, or a non-zero value on error
+ * 
+ * @see ucx_properties_fill()
+ * @see ucx_properties2map()
+ */
 int ucx_properties_load(UcxMap *map, FILE *file);
+/**
+ * Stores an UcxMap to a file.
+ * 
+ * The key/value-pairs are written by using the following format:
+ * 
+ * <code>[key] = [value]\\n</code>
+ * 
+ * @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);
 
 #ifdef	__cplusplus