Update docs with more info on different modes.

Author: gazpachoking

docs/conf.py

@@ -81,7 +81,7 @@
 """
 )
 
-intersphinx_mapping = {"python": ("https://docs.python.org/3.3", None)}
+intersphinx_mapping = {"python": ("https://docs.python.org/3.10", None)}
 
 
 # -- Options for HTML output ---------------------------------------------------

docs/index.rst

@@ -40,6 +40,63 @@ seen below.
 
 .. autofunction:: replace_refs
 
+The different modes
+-------------------
+
+``proxies``
+^^^^^^^^^^^
+
+The default mode (``proxies=True``) uses :class:`JsonRef` proxy objects to replace the
+reference objects in the document. For most purposes, they proxy everything to the
+referenced document. This can be useful for a few reasons:
+
+- The original reference object is still available with the
+  :attr:`JsonRef.__reference__` attribute.
+- :func:`dump` and :func:`dumps` can be used to output the document again, with the
+  references still intact. (Including changes made.)
+
+If you are using a tool that does not play nicely with the :class:`JsonRef` proxy
+objects, they can be turned off completely using ``proxies=False``. This is needed e.g.
+if you want to pass the data back to the stdlib :func:`json.dump` function.
+
+``lazy_load`` and ``load_on_repr``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, the references will not actually be resolved until the data is accessed
+(``lazy_load=True``.) This can be useful to limit the upfront processing of deeply
+nested, or otherwise complicated reference trees. To limit the lookups even more, the
+``load_on_repr`` argument can be set to ``False``, so that printing the document will
+not cause the references to load (this can be especially useful when debugging.) The
+downside of this mode is that exceptions when a reference cannot be loaded might be
+issued from more places when using the loaded document. Turning off lazy loading can
+make catching errors much easier.
+
+``merge_props``
+^^^^^^^^^^^^^^^
+
+When using this mode, extra properties from the reference object will be merged into
+the referenced document. e.g.::
+
+    >>> json = {
+        "a": {"$ref": "#/b", "extra": "blah"},
+        "b": {"real": "b"}
+    }
+    >>> print(replace_refs(json, merge_props=True))
+    {
+        "a": {"real": "b", "extra": "blah"},
+        "b": {"real": "b"}
+    }
+    >>> print(replace_refs(json))
+    {
+        "a": {"real": "b"},
+        "b": {"real": "b"}
+    }
+
+This is against the JSON reference spec, but some other JSON reference libraries also
+implement this behavior. It can be useful to e.g. extend common JSON schemas with extra
+properties. This behavior should not be used if you want your JSON documents to be
+usable with the widest possible array of tools.
+
 A note on ``base_uri``
 --------------------