QPDFJob: documentation

1 files changed, 22 insertions, 0 deletions

diff --git a/libqpdf/QPDFJob_json.cc b/libqpdf/QPDFJob_json.cc
index cc4e2ff7..c0de8666 100644
--- a/libqpdf/QPDFJob_json.cc
+++ b/libqpdf/QPDFJob_json.cc
@@ -29,6 +29,28 @@ namespace
         typedef std::function<void(char const*)> param_handler_t;
         typedef std::function<void(JSON)> json_handler_t;
 
+        // The code that calls these methods is automatically
+        // generated by generate_auto_job. This describes how we
+        // implement what it does. We keep a stack of handlers in
+        // json_handlers. The top of the stack is the "current" json
+        // handler, intially for the top-level object. Whenever we
+        // encounter a scalar, we add a handler using addBare,
+        // addParameter, or addChoices. Whenever we encounter a
+        // dictionary, we first add the dictionary handlers. Then we
+        // walk into the dictionary and, for each key, we register a
+        // dict key handler and push it to the stack, then do the same
+        // process for the key's value. Then we pop the key handler
+        // off the stack. When we encounter an array, we add the array
+        // handlers, push an item handler to the stack, call
+        // recursively for the array's single item (as this is what is
+        // expected in a schema), and pop the item handler. Note that
+        // we don't pop dictionary start/end handlers. The dictionary
+        // handlers and the key handlers are at the same level in
+        // JSONHandler. This logic is subtle and took several tries to
+        // get right. It's best understood by carefully understanding
+        // the behavior of JSONHandler, the JSON schema, and the code
+        // in generate_auto_job.
+
         void addBare(bare_handler_t);
         void addParameter(param_handler_t);
         void addChoices(char const** choices, bool required, param_handler_t);