From cc5485dac1f224f856ce48781278b357f61f74bd Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Tue, 1 Feb 2022 07:18:23 -0500 Subject: QPDFJob: documentation --- include/qpdf/QPDFJob.hh | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) (limited to 'include') diff --git a/include/qpdf/QPDFJob.hh b/include/qpdf/QPDFJob.hh index 5a8c88cc..64075bc1 100644 --- a/include/qpdf/QPDFJob.hh +++ b/include/qpdf/QPDFJob.hh @@ -62,10 +62,10 @@ class QPDFJob // the regular API. This is exposed in the C API, which makes it // easier to get certain high-level qpdf functionality from other // languages. If there are any command-line errors, this method - // will throw QPDFArgParser::Usage which is derived from - // std::runtime_error. Other exceptions may be thrown in some - // cases. Note that argc, and argv should be UTF-8 encoded. If you - // are calling this from a Windows Unicode-aware main (wmain), see + // will throw QPDFUsage which is derived from std::runtime_error. + // Other exceptions may be thrown in some cases. Note that argc, + // and argv should be UTF-8 encoded. If you are calling this from + // a Windows Unicode-aware main (wmain), see // QUtil::call_main_from_wmain for information about converting // arguments to UTF-8. This method will mutate arguments that are // passed to it. @@ -76,7 +76,7 @@ class QPDFJob // Initialize a QPDFJob from json. Passing partial = true prevents // this method from doing the final checks (calling // checkConfiguration) after processing the json file. This makes - // it possible to initialze QPDFJob in stages using multiple json + // it possible to initialize QPDFJob in stages using multiple json // files or to have a json file that can be processed from the CLI // with --job-json-file and be combined with other arguments. For // example, you might include only encryption parameters, leaving @@ -84,7 +84,11 @@ class QPDFJob // input and output files. initializeFromJson is called with // partial = true when invoked from the command line. To make sure // that the json file is fully valid on its own, just don't - // specify any other command-line flags. + // specify any other command-line flags. If there are any + // configuration errors, QPDFUsage is thrown. Some error messages + // may be CLI-centric. If an an exception tells you to use the + // "--some-option" option, set the "someOption" key in the JSON + // object instead. QPDF_DLL void initializeFromJson(std::string const& json, bool partial = false); @@ -160,7 +164,7 @@ class QPDFJob // 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 + // as a specific qpdf command. The example qpdf-job.cc contains an // example of this usage. You can also use initializeFromJson or // initializeFromArgv to initialize a QPDFJob object. @@ -180,6 +184,10 @@ class QPDFJob // with references. Returning pointers instead of references // makes for a more uniform interface. + // Maintainer documentation: see the section in README-maintainer + // called "HOW TO ADD A COMMAND-LINE ARGUMENT", which contains + // references to additional places in the documentation. + class Config; class AttConfig @@ -330,7 +338,10 @@ class QPDFJob // Return a top-level configuration item. See CONFIGURATION above // for details. If an invalid configuration is created (such as // supplying contradictory options, omitting an input file, etc.), - // QPDFUsage is thrown. + // QPDFUsage is thrown. Note that error messages are CLI-centric, + // but you can map them into config calls. For example, if an + // exception tells you to use the --some-option flag, you should + // call config()->someOption() instead. QPDF_DLL std::shared_ptr config(); -- cgit v1.2.3-70-g09d2