From 2e4e25a9342b7c938748bc8bb795e406dbcbfc39 Mon Sep 17 00:00:00 2001
From: Jay Berkenbilt <ejb@ql.org>
Date: Wed, 26 Jan 2022 17:31:31 -0500
Subject: [PATCH] Fix some comments

---
 README-maintainer       |  6 ------
 generate_auto_job       |  8 +-------
 include/qpdf/QPDFJob.hh | 37 +++++++++++++++++++++++++++++++++----
 job.sums                |  2 +-
 4 files changed, 35 insertions(+), 18 deletions(-)

diff --git a/README-maintainer b/README-maintainer
index b08cada2..7ea049dc 100644
--- a/README-maintainer
+++ b/README-maintainer
@@ -124,12 +124,6 @@ CODING RULES
 
 HOW TO ADD A COMMAND-LINE ARGUMENT
 
-QXXXQ update this to explain about all the automatic handlers, the
-difference between config, json, and argv, option tables, json
-dictionaries, etc. Make sure everthing that generate_auto_job does and
-its interaction with all the QPDFJob* source/header files is clearly
-explained.
-
 Command-line arguments are closely coupled with QPDFJob. To add a new
 command-line argument, add the option to the appropriate table in
 job.yml. This will automatically declare a method in the private
diff --git a/generate_auto_job b/generate_auto_job
index d2aa2ba4..7c9c9e6f 100755
--- a/generate_auto_job
+++ b/generate_auto_job
@@ -348,13 +348,7 @@ class Main:
     def prepare(self, data):
         self.decls = []
         self.init = []
-        self.jdata = {
-            # option: {
-            #   tables: set(),
-            #   help: string,
-            #   QXXXQ something for registering handler
-            # }
-        }
+        self.jdata = {}
 
         def add_jdata(flag, table):
             nonlocal self
diff --git a/include/qpdf/QPDFJob.hh b/include/qpdf/QPDFJob.hh
index 4a1f205e..076501ff 100644
--- a/include/qpdf/QPDFJob.hh
+++ b/include/qpdf/QPDFJob.hh
@@ -106,10 +106,10 @@ class QPDFJob
     QPDF_DLL
     bool createsOutput() const;
 
-    // CONFIGURATION
-    // (implemented in QPDFJob_config.cc)
-
+    // SEE BELOW FOR MORE PUBLIC METHODS AND CLASSES
   private:
+    // These structures are private but we need to define them before
+    // the public Config classes.
     struct CopyAttachmentFrom
     {
         std::string path;
@@ -146,6 +146,34 @@ class QPDFJob
     };
 
   public:
+    // CONFIGURATION
+
+    // Configuration classes are implemented in QPDFJob_config.cc.
+
+    // The config() method returns a shared pointer to a Config
+    // object. The Config object contains methods that correspond with
+    // qpdf command-line arguments. You can use a fluent interface to
+    // configure a QPDFJob object that would do exactly the same thing
+    // as a specific qpdf command. The example pdf-job.cc contains an
+    // example of this usage. You can also use initializeFromJson or
+    // initializeFromArgv to initialize a QPDFJob object.
+
+    // Notes about the Config methods:
+    //
+    // * Most of the method declarations are automatically generated
+    //   in header files that are included within the class
+    //   definitions. They correspond in predictable ways to the
+    //   command-line arguments and are generated from the same code
+    //   that generates the command-line argument parsing code.
+    //
+    // * Methods return pointers, rather than references, to
+    //   configuration objects. References might feel more familiar to
+    //   users of fluent interfaces, so why do we use pointers? The
+    //   main methods that create them return smart pointers so that
+    //   users can initialize them when needed, which you can't do
+    //   with references. Returning pointers instead of references
+    //   makes for a more uniform interface.
+
     class Config;
 
     class AttConfig
@@ -247,7 +275,6 @@ class QPDFJob
         Config* config;
     };
 
-    // Configuration is performed by calling methods XXX QXXXQ document
     class Config
     {
         friend class QPDFJob;
@@ -290,6 +317,8 @@ class QPDFJob
     };
     friend class Config;
 
+    // Return a top-level configuration item. See CONFIGURATION above
+    // for details.
     QPDF_DLL
     std::shared_ptr<Config> config();
 
diff --git a/job.sums b/job.sums
index 9e2a48c9..f12ea23d 100644
--- a/job.sums
+++ b/job.sums
@@ -1,5 +1,5 @@
 # Generated by generate_auto_job
-generate_auto_job e5c58868f4cb2c3ec1689bf44fb57cc57930f981f52fa4aa21d6b990a83f7163
+generate_auto_job bf02a4e1ce64ab413a2ca8812041d50e55fe3c892e7e6010b9c258d71420310e
 include/qpdf/auto_job_c_att.hh 7ad43bb374c1370ef32ebdcdcb7b73a61d281f7f4e3f12755585872ab30fb60e
 include/qpdf/auto_job_c_copy_att.hh 32275d03cdc69b703dd7e02ba0bbe15756e714e9ad185484773a6178dc09e1ee
 include/qpdf/auto_job_c_enc.hh 72e138c7b96ed5aacdce78c1dec04b1c20d361faec4f8faf52f64c1d6be99265