QPDFJob: documentation

4 files changed, 26 insertions, 4 deletions

diff --git a/libqpdf/QPDFJob.cc b/libqpdf/QPDFJob.cc
index 1c6a16d6..a06f87bc 100644
--- a/libqpdf/QPDFJob.cc
+++ b/libqpdf/QPDFJob.cc
@@ -646,7 +646,6 @@ QPDFJob::createsOutput() const
 void
 QPDFJob::checkConfiguration()
 {
-    // QXXXQ messages are CLI-centric
     if (m->replace_input)
     {
         if (m->outfilename)
@@ -722,7 +721,8 @@ QPDFJob::checkConfiguration()
     {
         QTC::TC("qpdf", "qpdf same file error");
         usage("input file and output file are the same;"
-              " use --replace-input to intentionally overwrite the input file");
+              " use --replace-input to intentionally"
+              " overwrite the input file");
     }
 }
 
diff --git a/libqpdf/QPDFJob_config.cc b/libqpdf/QPDFJob_config.cc
index fb61924c..68eaf5c8 100644
--- a/libqpdf/QPDFJob_config.cc
+++ b/libqpdf/QPDFJob_config.cc
@@ -28,7 +28,6 @@ QPDFJob::Config::emptyInput()
 {
     if (o.m->infilename == 0)
     {
-        // QXXXQ decide whether to fix this or just leave the comment:
         // Various places in QPDFJob.cc know that the empty string for
         // infile means empty. This means that passing "" as the
         // argument to inputFile, or equivalently using "" as a
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);
diff --git a/libqpdf/qpdf/auto_job_help.hh b/libqpdf/qpdf/auto_job_help.hh
index 49ac3494..38d275b5 100644
--- a/libqpdf/qpdf/auto_job_help.hh
+++ b/libqpdf/qpdf/auto_job_help.hh
@@ -812,7 +812,8 @@ This option is repeatable. If given, only specified objects will
 be shown in the "objects" key of the JSON output. Otherwise, all
 objects will be shown.
 )");
-ap.addOptionHelp("--job-json-help", "json", "show format of job JSON", R"(Describe the format of the QPDFJob JSON input.
+ap.addOptionHelp("--job-json-help", "json", "show format of job JSON", R"(Describe the format of the QPDFJob JSON input used by
+--job-json-file.
 )");
 ap.addHelpTopic("testing", "options for testing or debugging", R"(The options below are useful when writing automated test code that
 includes files created by qpdf or when testing qpdf itself.