update README

diff --git a/libs/json/README b/libs/json/README
index 3e494e9dc6855c449333d1dde05f43ae1e3287d4..51b9a10487df2917f644fda4ccae9568634a5b5d 100644 (file)
--- a/libs/json/README
+++ b/libs/json/README
@@ -16,7 +16,7 @@ the input), or (c) a parsing exception.
 
 
 JSON <-> OCaml conversion function generator:
--------------------------------------------
+---------------------------------------------
 
 The generator (in gen_json_conv/) takes as input a file containing _only_ OCaml
 type definitions, and generates an output file containing functions to
@@ -49,3 +49,38 @@ The generated functions are named <ocaml_type>_of_json and
 <ocaml_type>_to_json for each input type defined.  *_of_json functions
 can fail with a conversion exception.
 
+
+JSON-RPC boilerplate generator:
+-------------------------------
+
+This generator (in gen_rpc/) takes JSON-RPC definitions specified in a
+json-format, and generates the client-side boilerplate to invoke, and
+the server-side boilerplate to implement, these RPCs.
+
+The definitions specify the name and type of the JSON-RPC:
+notification or procedure call (or method-call), the names and types
+of the arguments, and, only for procedure calls: the type of the
+response.  Documentation annotations can be specified for each call,
+its arguments and return value.
+
+The client-side generated code provides a wrapper function for each
+rpc that takes native ocaml arguments of the specified type, converts
+them into json values, and returns a value of type
+Json_rpc.rpc_request.  This can be converted into a json-rpc value
+using Json_rpc.rpc_request_to_json, and sent over the wire.
+
+The server-side generated code provides a dispatch function, that
+takes a json-rpc value, extracts the method or notification name,
+converts the supplied parameters into native ocaml values that those
+functions expect according to the specificaton, and invokes them with
+those argument values.
+
+These definitions are organized by server-endpoint, and a definition
+is also required for each server that specifies a error-handler
+function that catches exceptions thrown by the invoked rpc code, and
+returns values of type Json_rpc.rpc_error.  Note that exceptions are
+not handled for notifications, and that the application will see and
+need to handle these exceptions.
+
+The generated code collects the boilerplate into modules named after
+the server-endpoints.