Add some more detail about how to use json-c in README.md.

1 files changed, 31 insertions, 1 deletions

diff --git a/README.md b/README.md
index ff15eab..fc128f5 100644
--- a/README.md
+++ b/README.md
@@ -238,8 +238,38 @@ following more specific header files:
 * json_tokener.h - Methods for parsing and serializing json-c object trees.
 * json_pointer.h - JSON Pointer (RFC 6901) implementation for retrieving
                    objects from a json-c object tree.
-* json_object_iterator.h - Methods for iterating over single json_object instances.
+* json_object_iterator.h - Methods for iterating over single json_object instances.  (See also `json_object_object_foreach()` in json_object.h)
 * json_visit.h   - Methods for walking a tree of json-c objects.
 * json_util.h    - Miscelleanous utility functions.
 
 For a full list of headers see [files.html](http://json-c.github.io/json-c/json-c-current-release/doc/html/files.html)
+
+The primary type in json-c is json_object.  It describes a reference counted
+tree of json objects which are created by either parsing text with a
+json_tokener (i.e. `json_tokener_parse_ex()`), or by creating
+(with `json_object_new_object()`, `json_object_new_int()`, etc...) and adding
+(with `json_object_object_add()`, `json_object_array_add()`, etc...) them 
+individually.
+Typically, every object in the tree will have one reference, from it's parent.
+When you are done with the tree of objects, you call json_object_put() on just
+the root object to free it, which recurses down through any child objects
+calling json_object_put() on each one of those in turn.
+
+You can get a reference to a single child 
+(`json_object_object_get()` or `json_object_array_get_idx()`)
+and use that object as long as its parent is valid.  
+If you need a child object to live longer than its parent, you can
+increment the child's refcount (`json_object_get()`) to allow it to survive
+the parent being freed or it being removed from its parent
+(`json_object_object_del()` or `json_object_array_del_idx()`)
+
+When parsing text, the json_tokener object is independent from the json_object
+that it returns.  It can be allocated (`json_tokener_new()`)
+used ones or multiple times (`json_tokener_parse_ex()`, and
+freed (`json_tokener_free()`) while the json_object objects live on.
+
+A json_object tree can be serialized back into a string with 
+`json_object_to_json_string_ext()`.  The string that is returned 
+is only valid until the next "to_json_string" call on that same object.
+Also, it is freed when the json_object is freed.
+