TODO and comments item for pipeContentStreams

2 files changed, 13 insertions, 2 deletions

diff --git a/include/qpdf/QPDFObjectHandle.hh b/include/qpdf/QPDFObjectHandle.hh
index ef6ff42e..7738fd77 100644
--- a/include/qpdf/QPDFObjectHandle.hh
+++ b/include/qpdf/QPDFObjectHandle.hh
@@ -393,7 +393,12 @@ class QPDFObjectHandle
     // messages. The all_description argument is initialized to
     // something that could be used to describe the result of the
     // pipeline. It is the description amended with the identifiers of
-    // the underlying objects.
+    // the underlying objects. Please note that if there is an array
+    // of content streams, p->finish() is called after each stream. If
+    // you pass a pipeline that doesn't allow write() to be called
+    // after finish(), you can wrap it in an instance of
+    // Pl_Concatenate and then call manualFinish() on the
+    // Pl_Concatenate pipeline at the end.
     QPDF_DLL
     void pipeContentStreams(Pipeline* p, std::string const& description,
                             std::string& all_description);
@@ -419,6 +424,7 @@ class QPDFObjectHandle
     void parsePageContents(ParserCallbacks* callbacks);
     QPDF_DLL
     void filterPageContents(TokenFilter* filter, Pipeline* next = 0);
+    // See comments for QPDFPageObjectHelper::pipePageContents.
     QPDF_DLL
     void pipePageContents(Pipeline* p);
     QPDF_DLL
diff --git a/include/qpdf/QPDFPageObjectHelper.hh b/include/qpdf/QPDFPageObjectHelper.hh
index 87dad8d4..a197ece7 100644
--- a/include/qpdf/QPDFPageObjectHelper.hh
+++ b/include/qpdf/QPDFPageObjectHelper.hh
@@ -145,7 +145,12 @@ class QPDFPageObjectHelper: public QPDFObjectHelper
 
     // Pipe a page's contents through the given pipeline. This method
     // works whether the contents are a single stream or an array of
-    // streams. Call on a page object.
+    // streams. Call on a page object. Please note that if there is an
+    // array of content streams, p->finish() is called after each
+    // stream. If you pass a pipeline that doesn't allow write() to be
+    // called after finish(), you can wrap it in an instance of
+    // Pl_Concatenate and then call manualFinish() on the
+    // Pl_Concatenate pipeline at the end.
     QPDF_DLL
     void pipePageContents(Pipeline* p);