Feature: Added comments/docs for JSON renderer in the header

src/json.h

@@ -13,28 +13,99 @@
 
 #include <stdint.h>
 
+/*
+ * Overview:
+ * ---------
+ *  * First a renderer is created using json_renderer_create().
+ *  * Elements can then be written to the renderer in order they appear in the
+ *    final JSON using json_renderer_write_*().
+ *  * Objects and arrays can be opened and closed using json_renderer_begin()
+ *    and json_renderer_end()
+ *  * Objects and arrays are automatically closed on json_renderer_finish()
+ *  * json_renderer_finish() is used to fetch the final rendering result
+ *    and destroy the renderer object. The renderer object is invalid after this.
+ *    The returned value must be freed using free() by the caller.
+ */
+
+/* Dummy value used when no flags are passed. */
 #define JSON_RENDERER_FLAGS_NONE            0
 
+/* Enum of JSON element types, may not include all element types */
 typedef enum {
+    /* Objects ('{key:value}') */
     JSON_ELEMENT_TYPE_OBJECT,
+    /* Arrays ('[a,b,c]') */
     JSON_ELEMENT_TYPE_ARRAY
 } json_element_type_t;
 
+/* Type of the renderer */
 typedef struct json_renderer_tag json_renderer_t;
 
+/*
+ * json_renderer_create() creates a renderer object using
+ * the given flags. See the definition of the flags for details.
+ * If no flags are to be passed, JSON_RENDERER_FLAGS_NONE MUST be used.
+ */
 json_renderer_t * json_renderer_create(unsigned int flags);
 
+/*
+ * json_renderer_finish() finishes the rendering, destroys the renderer,
+ * and returns the rendered JSON.
+ * The renderer is invalid after this and MUST NOT be reused.
+ * The returned buffer MUST be freed by the caller using free().
+ */
 char * json_renderer_finish(json_renderer_t **rendererptr);
 
+/*
+ * json_renderer_begin() begins a new sub-element that might be an object or array.
+ * json_renderer_begin() MUST be matched with a correspoinding json_renderer_end()
+ * unless at end of the document as all elements that are still open are closed
+ * automatically.
+ */
 void json_renderer_begin(json_renderer_t *renderer, json_element_type_t type);
+/*
+ * json_renderer_end() closes the current sub-element that was opened using json_renderer_begin().
+ */
 void json_renderer_end(json_renderer_t *renderer);
 
+/*
+ * json_renderer_write_key() writes a key for a object key-value pair.
+ * Parameters work the same as for json_renderer_write_string().
+ */
 void json_renderer_write_key(json_renderer_t *renderer, const char *key, unsigned int flags);
 
+/*
+ * json_renderer_write_null() writes a null-value.
+ */
 void json_renderer_write_null(json_renderer_t *renderer);
+
+/*
+ * json_renderer_write_boolean() writes a boolean value.
+ * The parameter val is interpreted by standard C rules for truth.
+ */
+
 void json_renderer_write_boolean(json_renderer_t *renderer, int val);
+
+/*
+ * json_renderer_write_string() writes a string value.
+ * The parameter string must be in UTF-8 encoding and \0-terminated.
+ * The parameter flags can be used to hint the rendering engine.
+ * If no flags are given JSON_RENDERER_FLAGS_NONE MUST be given.
+ */
 void json_renderer_write_string(json_renderer_t *renderer, const char *string, unsigned int flags);
+
+/*
+ * json_renderer_write_int() writes am signed integer value.
+ * Note: JSON does not define specific types of numbers (signed/unsigned, integer/fixed ponint/floating point)
+ *       so this writes the integer as generic number.
+ */
 void json_renderer_write_int(json_renderer_t *renderer, intmax_t val);
+
+/*
+ * json_renderer_write_uint() writes an unsigned integer value.
+ * Note: JSON does not define specific types of numbers (signed/unsigned, integer/fixed ponint/floating point)
+ *       so this writes the integer as generic number.
+ */
 void json_renderer_write_uint(json_renderer_t *renderer, uintmax_t val);
 
 #endif