1 files changed, 30 insertions, 20 deletions
diff --git a/json.h b/json.h
index 17a9a08..3f53f6a 100644
--- a/json.h
+++ b/json.h
@@ -55,6 +55,17 @@ typedef enum
 
 typedef struct JSON JSON;
 
+/*
+ * All strings in JSON nodes are UTF-8-encoded, not server encoded.
+ * The reason for this is because we need to encode/decode individual
+ * Unicode codepoints when dealing with escape characters, but there
+ * are no functions for efficiently converting between Unicode code points
+ * and any server encoding.
+ *
+ * As an exception to the rule, if you only use node factory functions and
+ * json_encode without the JSONOPT_ESCAPE_UNICODE option, you may operate
+ * in the server encoding instead.
+ */
 struct JSON
 {
 	json_type	type;
@@ -115,6 +126,8 @@ struct JSON
 };
 
 
+/*** Encoding / decoding / validation ***/
+
 bool		json_validate(const char *str);
 bool		json_validate_server_encoded(const char *str);
 JSON	   *json_decode(const char *str);
@@ -124,19 +137,10 @@ JSON	   *json_decode(const char *str);
 #define JSONOPT_NO_TRIM			4
 char	   *json_encode(JSON * node, int options);
 
-/* Determines the type of a JSON string without fully decoding it.
- * Expects the given string to be valid JSON string.
- * Might return JSON_INVALID if something is wrong with the input. */
 json_type	json_text_type(const char *str, size_t nbytes);
 
-/*
- * Free a JSON node and all its descendants.
- *
- * Do not use this function if you have performed json_replace_value on
- * a descendant, as this function relies on each node's ->parent field
- * being trustworthy.
- */
-void		json_delete(JSON * node);
+
+/*** Lookup / traversal ***/
 
 #define json_foreach(child, parent) \
 	for ((child) = json_head(parent); (child) != NULL; (child) = (child)->next)
@@ -154,19 +158,15 @@ json_head(JSON * parent)
 	}
 }
 
-char	   *json_decode_string(const char **sp, size_t *length, bool strict);
-char	   *json_encode_string(const char *str, size_t length, char quote, bool escape_unicode);
 
-/* Add child to parent, putting it at the end. */
-void		json_append(JSON * parent, JSON * child);
+/*** Parent/child manipulation ***/
 
-/* Remove node from its parent. */
+void		json_append(JSON * parent, JSON * child);
 void		json_remove(JSON * node);
 
-/* Update the value of a node, preserving position and key information. */
-void		json_replace_value(JSON * node, JSON * replacement);
 
-/* Node factory functions */
+/*** Node factory functions ***/
+
 JSON	   *json_mknode(json_type type);
 JSON	   *json_mkbool(bool v_bool);
 JSON	   *json_mkstring(const char *str, size_t length);
@@ -182,9 +182,11 @@ json_mkobject(void)
 	return json_mknode(JSON_OBJECT);
 }
 
+
+/*** Value get/set functions ***/
+
 void		json_touch_value(JSON * node);
 
-/* Node value get/set functions. */
 static inline bool
 json_get_bool(JSON * node)
 {
@@ -203,4 +205,12 @@ void		json_set_string(JSON * node, const char *str, size_t length);
 const char *json_get_number(JSON * node);
 void		json_set_number(JSON * node, const char *number, size_t length);
 
+void		json_replace_value(JSON * node, JSON * replacement);
+
+
+/*** Miscellaneous utility functions ***/
+
+char	   *json_decode_string(const char **sp, size_t *length, bool strict);
+char	   *json_encode_string(const char *str, size_t length, char quote, bool escape_unicode);
+
 #endif