Use the default logger for other writes to stdout/stderr

When there is no context for writing output or error messages, use the
default logger.

2 files changed, 18 insertions, 5 deletions

diff --git a/include/qpdf/QPDFLogger.hh b/include/qpdf/QPDFLogger.hh
index 340706c9..cd439caa 100644
--- a/include/qpdf/QPDFLogger.hh
+++ b/include/qpdf/QPDFLogger.hh
@@ -33,6 +33,19 @@ class QPDFLogger
     QPDF_DLL
     QPDFLogger();
 
+    // Return the default logger. In general, you should use the
+    // default logger. You can also create your own loggers and use
+    // them QPDF and QPDFJob objects, but there are few reasons to do
+    // so. One reason may if you are using multiple QPDF or QPDFJob
+    // objects in different threads and want to capture output and
+    // errors to different streams. (Note that a single QPDF or
+    // QPDFJob can't be safely used from multiple threads, but it is
+    // safe to use separate QPDF and QPDFJob objects on separate
+    // threads.) Another possible reason would be if you are writing
+    // an application that uses the qpdf library directly and qpdf is
+    // also used by a downstream library or if you are using qpdf from
+    // a library and don't want to interfere with potential uses of
+    // qpdf by other libraries or applications.
     QPDF_DLL
     static std::shared_ptr<QPDFLogger> defaultLogger();
 
diff --git a/include/qpdf/QPDFObjectHandle.hh b/include/qpdf/QPDFObjectHandle.hh
index 557330e5..7ab2652a 100644
--- a/include/qpdf/QPDFObjectHandle.hh
+++ b/include/qpdf/QPDFObjectHandle.hh
@@ -1411,14 +1411,14 @@ class QPDFObjectHandle
     // End legacy page helpers
 
     // Issue a warning about this object if possible. If the object
-    // has a description, a warning will be issued. Otherwise, if
-    // throw_if_no_description is true, throw an exception. Otherwise
-    // do nothing. Objects read normally from the file have
+    // has a description, a warning will be issued using the owning
+    // QPDF as context. Otherwise, a message will be written to the
+    // default logger's error stream, which is standard error if not
+    // overridden. Objects read normally from the file have
     // descriptions. See comments on setObjectDescription for
     // additional details.
     QPDF_DLL
-    void warnIfPossible(
-        std::string const& warning, bool throw_if_no_description = false);
+    void warnIfPossible(std::string const& warning);
 
     // Initializers for objects.  This Factory class gives the QPDF
     // class specific permission to call factory methods without