From 45049fb8745f5f3551083a6587ced76c2aef3a1c Mon Sep 17 00:00:00 2001
From: Eric Fischer <enf@pobox.com>
Date: Fri, 7 Feb 2014 16:48:06 -0800
Subject: [PATCH] More documentation

---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/README.md b/README.md
index 4818d0c..d753820 100644
--- a/README.md
+++ b/README.md
@@ -19,3 +19,44 @@ You can also read from anything you want by calling <code>json_begin()</code>
 with your own <code>read()</code> and <code>peek()</code> functions that
 return or preview, respectively, the next UTF-8 byte from your input stream.
 
+Reading single JSON objects
+---------------------------
+
+The simplest form is <code>json_read_tree()</code>, which reads a complete
+JSON object from the stream, or NULL if there was an error or on end of file.
+Call <code>json_free()</code> on the object when you are done with it,
+and <code>json_end()</code> on the parser.
+
+You can continue calling <code>json_read_tree()</code> to read additional objects
+from the same stream. This is not standard JSON, but is useful for something like
+the Twitter filter stream that contains a series of JSON objects separated by
+newlines, without a wrapper array that contains them all.
+
+Reading JSON streams
+--------------------
+
+With something like GeoJSON, where it is common to have a large wrapper array
+that contains many smaller items that are often useful to consider separately,
+you can read the stream one token at a time.
+
+The normal form is <code>json_read()</code>, which returns the next complete
+object from the stream. This can be a single string, number, <code>true</code>,
+<code>false</code>, or <code>null</code>, or it can be an array or hash that
+contains other primitive or compound objects.
+
+Note that each array or hash will be returned following all the objects that it contains.
+The outermost object will be the same one that <code>json_read_tree()</code> would
+have returned, and you can tell that it is the outer object because its
+<code>parent</code> field is null.
+
+You can call <code>json_free()</code> on each object as you are finished with it,
+or wait until the end and call <code>json_free()</code> on the outer object
+which will recursively free everything that it contains. Freeing an object before
+its container is complete also removes it from its parent array or hash so that
+there are not dangling references left to it.
+
+Reading JSON streams with callbacks
+-----------------------------------
+
+If you are outputting a new stream as you read instead of just looking for the
+sub-objects that interest you,