Add next to Pl_String and fix comments

1 files changed, 15 insertions, 3 deletions

diff --git a/include/qpdf/Pl_String.hh b/include/qpdf/Pl_String.hh
index a858257c..327598da 100644
--- a/include/qpdf/Pl_String.hh
+++ b/include/qpdf/Pl_String.hh
@@ -19,11 +19,23 @@
 // continue to consider qpdf to be licensed under those terms. Please
 // see the manual for additional information.
 
-// End-of-line pipeline that simply writes its data to a stdio FILE* object.
-
 #ifndef PL_STRING_HH
 #define PL_STRING_HH
 
+// This pipeline accumulates the data passed to it into a std::string,
+// a reference to which is passed in at construction. Each subsequent
+// use of this pipeline appends to the data accumulated so far.
+//
+// For this pipeline, "next" may be null. If a next pointer is
+// provided, this pipeline will also pass the data through to it and
+// will forward finish() to it.
+//
+// It is okay to not call finish() on this pipeline. This makes it
+// easy to stick this in front of another pipeline to capture data
+// that is written to the other pipeline without interfering with when
+// finish is called on the other pipeline and without having to put a
+// Pl_Concatenate after it.
+
 #include <qpdf/Pipeline.hh>
 
 #include <string>
@@ -32,7 +44,7 @@ class QPDF_DLL_CLASS Pl_String: public Pipeline
 {
   public:
     QPDF_DLL
-    Pl_String(char const* identifier, std::string& s);
+    Pl_String(char const* identifier, Pipeline* next, std::string& s);
     QPDF_DLL
     virtual ~Pl_String();