Fix some comments

Jay Berkenbilt
1 parent c62ab2ee
Showing 4 changed files with 35 additions and 18 deletions
README-maintainer
generate_auto_job
include/qpdf/QPDFJob.hh
job.sums
@@ -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
@@ -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
@@ -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();
 # 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