Fix doc typos

m-holger
1 parent 3c5700c2
Showing 24 changed files with 65 additions and 66 deletions
.git-blame-ignore-revs
examples/pdf-invert-images.cc
examples/pdf-name-number-tree.cc
examples/pdf-set-form-values.cc
include/qpdf/ClosedFileInputSource.hh
include/qpdf/JSON.hh
include/qpdf/PDFVersion.hh
include/qpdf/Pl_Concatenate.hh
include/qpdf/QPDFAnnotationObjectHelper.hh
include/qpdf/QPDFDocumentHelper.hh
include/qpdf/QPDFEFStreamObjectHelper.hh
include/qpdf/QPDFLogger.hh
include/qpdf/QPDFNameTreeObjectHelper.hh
include/qpdf/QPDFNumberTreeObjectHelper.hh
include/qpdf/QPDFObjectHelper.hh
include/qpdf/QPDFOutlineDocumentHelper.hh
include/qpdf/QPDFOutlineObjectHelper.hh
include/qpdf/QPDFPageDocumentHelper.hh
include/qpdf/QPDFWriter.hh
include/qpdf/QUtil.hh
@@ -14,3 +14,4 @@ d740c6ccced02147f84a39d5e5f0984d12bac6cb
 60965d5f4d608bdccc2ffd4e8753e12cbbbd71d2
 # Reflow comments and strings to 100 columns
 698a70e6a84cf7c0db667e9d9e021b4c34c85a3e
+3c5700c255f4603b5df9c6d183d13dd71a083cc3
@@ -120,9 +120,9 @@ main(int argc, char* argv[])
                 QPDFObjectHandle color_space = image_dict.getKey("/ColorSpace");
                 QPDFObjectHandle bits_per_component = image_dict.getKey("/BitsPerComponent");
-                // For our example, we can only work with images 8-bit grayscale images that we can
-                // fully decode.  Use pipeStreamData with a null pipeline to determine whether the
-                // image is filterable.  Directly inspect keys to determine the image type.
+                // For our example, we can only work with 8-bit grayscale images that we can fully
+                // decode.  Use pipeStreamData with a null pipeline to determine whether the image
+                // is filterable.  Directly inspect keys to determine the image type.
                 if (image.pipeStreamData(nullptr, qpdf_ef_compress, qpdf_dl_all) &&
                     color_space.isNameAndEquals("/DeviceGray") && bits_per_component.isInteger() &&
                     (bits_per_component.getIntValue() == 8)) {
@@ -41,7 +41,7 @@ main(int argc, char* argv[])
     // (root), and write an empty PDF to a file. The PDF will have no pages and won't be viewable,
     // but you can look at it in a text editor to see the resulting structure of the PDF.
-    // Create a dictionary off the root where we will hang our name and number tree.
+    // Create a dictionary off the root where we will hang our name and number trees.
     auto root = qpdf.getRoot();
     auto example = QPDFObjectHandle::newDictionary();
     root.replaceKey("/Example", example);
@@ -38,7 +38,7 @@ main(int argc, char* argv[])
         qpdf.processFile(infilename);
         // We will iterate through form fields by starting at the page level and looking at each
-        // field for each page. We could also called QPDFAcroFormDocumentHelper::getFormFields to
+        // field for each page. We could also call QPDFAcroFormDocumentHelper::getFormFields to
         // iterate at the field level, but doing it as below illustrates how we can map from
         // annotations to fields.
@@ -51,12 +51,12 @@ main(int argc, char* argv[])
                 // value.
                 QPDFFormFieldObjectHelper ffh = afdh.getFieldForAnnotation(annot);
                 if (ffh.getFieldType() == "/Tx") {
-                    // Set the value. Passing false as the second value prevents qpdf from setting
-                    // /NeedAppearances to true (but will not turn it off if it's already on), so we
-                    // call generateAppearance after setting the value. You may or may not want to
-                    // do this depending on whether the appearance streams generated by qpdf are
-                    // good enough for your purposes. For additional details, please see comments in
-                    // QPDFFormFieldObjectHelper.hh for this method.
+                    // Set the value. Passing false as the second parameter prevents qpdf from
+                    // setting /NeedAppearances to true (but will not turn it off if it's already
+                    // on), so we call generateAppearance after setting the value. You may or may
+                    // not want to do this depending on whether the appearance streams generated by
+                    // qpdf are good enough for your purposes. For additional details, please see
+                    // comments in QPDFFormFieldObjectHelper.hh for this method.
                     ffh.setV(value, false);
                     ffh.generateAppearance(annot);
                 }
@@ -20,9 +20,9 @@
 #define QPDF_CLOSEDFILEINPUTSOURCE_HH
 // This is an input source that reads from files, like FileInputSource, except that it opens and
-// close the file surrounding every operation. This decreases efficiency, but it allows many more of
-// these to exist at once than the maximum number of open file descriptors. This is used for merging
-// large numbers of files.
+// closes the file surrounding every operation. This decreases efficiency, but it allows many more
+// of these to exist at once than the maximum number of open file descriptors. This is used for
+// merging large numbers of files.
 #include <qpdf/InputSource.hh>
 #include <qpdf/PointerHolder.hh> // unused -- remove in qpdf 12 (see #785)
@@ -69,7 +69,7 @@ class JSON
     // to pass that `first` through to all the methods that are called to add top-level items to the
     // container as well as to close the container. This lets the JSON object use it to keep track
     // of when it's writing a first object and when it's not. If incrementally writing multiple
-    // levels of depth, a new `first` should used for each new container that is opened.
+    // levels of depth, a new `first` should be used for each new container that is opened.
     //
     // "depth" -- Indicate the level of depth. This is used for consistent indentation. When writing
     // incrementally, whenever you call a method to add an item to a container, the value of `depth`
@@ -208,7 +208,7 @@ class JSON
     QPDF_DLL
     bool checkSchema(JSON schema, std::list<std::string>& errors);
-    // An pointer to a Reactor class can be passed to parse, which will enable the caller to react
+    // A pointer to a Reactor class can be passed to parse, which will enable the caller to react
     // to incremental events in the construction of the JSON object. This makes it possible to
     // implement SAX-like handling of very large JSON objects.
     class QPDF_DLL_CLASS Reactor
@@ -16,9 +16,6 @@
 // License. At your option, you may continue to consider qpdf to be licensed under those terms.
 // Please see the manual for additional information.
-// This class implements a simple writer for saving QPDF objects to new PDF files.  See comments
-// through the header file for additional details.
-
 #ifndef PDFVERSION_HH
 #define PDFVERSION_HH
@@ -19,7 +19,7 @@
 #ifndef PL_CONCATENATE_HH
 #define PL_CONCATENATE_HH
-// This pipeline will drop all regular finished calls rather than passing them onto next.  To finish
+// This pipeline will drop all regular finish calls rather than passing them onto next.  To finish
 // downstream streams, call manualFinish.  This makes it possible to pipe multiple streams (e.g.
 // with QPDFObjectHandle::pipeStreamData) to a downstream like Pl_Flate that can't handle multiple
 // calls to finish().
@@ -40,7 +40,7 @@ class QPDFAnnotationObjectHelper: public QPDFObjectHelper
     // besides widget annotations, but they are implemented with form fields so that they can
     // properly handle form fields when needed.
-    // Return the subtype of the annotation as a string (e.g. "/Widget"). Returns the empty string
+    // Return the subtype of the annotation as a string (e.g. "/Widget"). Returns an empty string
     // if the subtype (which is required by the spec) is missing.
     QPDF_DLL
     std::string getSubtype();
@@ -51,7 +51,7 @@ class QPDFAnnotationObjectHelper: public QPDFObjectHelper
     QPDF_DLL
     QPDFObjectHandle getAppearanceDictionary();
-    // Return the appearance state as given in "/AS", or the empty string if none is given.
+    // Return the appearance state as given in "/AS", or an empty string if none is given.
     QPDF_DLL
     std::string getAppearanceState();
@@ -23,12 +23,12 @@
 #include <qpdf/QPDF.hh>
 // This is a base class for QPDF Document Helper classes. Document helpers are classes that provide
-// a convenient, higher-level API for accessing document-level structures with a PDF file. Document
-// helpers are always initialized with a reference to a QPDF object, and the object can always be
-// retrieved. The intention is that you may freely intermix use of document helpers with the
-// underlying QPDF object unless there is a specific comment in a specific helper method that says
-// otherwise. The pattern of using helper objects was introduced to allow creation of higher level
-// helper functions without polluting the public interface of QPDF.
+// a convenient, higher-level API for accessing document-level structures within a PDF file.
+// Document helpers are always initialized with a reference to a QPDF object, and the object can
+// always be retrieved. The intention is that you may freely intermix use of document helpers with
+// the underlying QPDF object unless there is a specific comment in a specific helper method that
+// says otherwise. The pattern of using helper objects was introduced to allow creation of higher
+// level helper functions without polluting the public interface of QPDF.
 class QPDF_DLL_CLASS QPDFDocumentHelper
 {
@@ -55,7 +55,7 @@ class QPDFEFStreamObjectHelper: public QPDFObjectHelper
     // Return the checksum as stored in the object as a binary string. This does not check
     // consistency with the data. If not present, return an empty string. The PDF spec specifies
     // this as an MD5 checksum and notes that it is not to be used for security purposes since MD5
-    // is known not to be secure.
+    // is known to be insecure.
     QPDF_DLL
     std::string getChecksum();
@@ -31,14 +31,14 @@ class QPDFLogger
     static std::shared_ptr<QPDFLogger> create();
     // 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.
+    // your own loggers and use them with QPDF and QPDFJob objects, but there are few reasons to do
+    // so. One reason may be that 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();
@@ -52,7 +52,7 @@ class QPDF_DLL_CLASS QPDFNameTreeObjectHelper: public QPDFObjectHelper
     QPDF_DLL
     virtual ~QPDFNameTreeObjectHelper();
-    // Return whether the number tree has an explicit entry for this number.
+    // Return whether the name tree has an explicit entry for this name.
     QPDF_DLL
     bool hasName(std::string const& utf8);
@@ -151,7 +151,7 @@ class QPDF_DLL_CLASS QPDFNameTreeObjectHelper: public QPDFObjectHelper
     iterator insert(std::string const& key, QPDFObjectHandle value);
     // Remove an item. Return true if the item was found and removed; otherwise return false. If
-    // value is not null, initialize it to the value that was removed.
+    // value is not nullptr, initialize it to the value that was removed.
     QPDF_DLL
     bool remove(std::string const& key, QPDFObjectHandle* value = nullptr);
@@ -145,7 +145,7 @@ class QPDF_DLL_CLASS QPDFNumberTreeObjectHelper: public QPDFObjectHelper
         value_type ivalue;
     };
-    // The iterator looks like map iterator, so i.first is a string and i.second is a
+    // The iterator looks like map iterator, so i.first is a numtree_number and i.second is a
     // QPDFObjectHandle. Incrementing end() brings you to the first item. Decrementing end() brings
     // you to the last item.
     QPDF_DLL
@@ -166,7 +166,7 @@ class QPDF_DLL_CLASS QPDFNumberTreeObjectHelper: public QPDFObjectHelper
     iterator insert(numtree_number key, QPDFObjectHandle value);
     // Remove an item. Return true if the item was found and removed; otherwise return false. If
-    // value is not null, initialize it to the value that was removed.
+    // value is not nullptr, initialize it to the value that was removed.
     QPDF_DLL
     bool remove(numtree_number key, QPDFObjectHandle* value = nullptr);
@@ -26,7 +26,7 @@
 // This is a base class for QPDF Object Helper classes. Object helpers are classes that provide a
 // convenient, higher-level API for working with specific types of QPDF objects. Object helpers are
 // always initialized with a QPDFObjectHandle, and the underlying object handle can always be
-// retrieved. The intention is that you may freely intermix use of document helpers with the
+// retrieved. The intention is that you may freely intermix use of object helpers with the
 // underlying QPDF objects unless there is a specific comment in a specific helper method that says
 // otherwise. The pattern of using helper objects was introduced to allow creation of higher level
 // helper functions without polluting the public interface of QPDFObjectHandle.
@@ -55,7 +55,7 @@ class QPDFOutlineDocumentHelper: public QPDFDocumentHelper
     QPDF_DLL
     QPDFObjectHandle resolveNamedDest(QPDFObjectHandle name);
-    // Return a list outlines that are known to target the specified page
+    // Return a list outlines that are known to target the specified page.
     QPDF_DLL
     std::vector<QPDFOutlineObjectHelper> getOutlinesForPage(QPDFObjGen const&);
@@ -37,7 +37,7 @@ class QPDFOutlineObjectHelper: public QPDFObjectHelper
     virtual ~QPDFOutlineObjectHelper()
     {
         // This must be cleared explicitly to avoid circular references that prevent cleanup of
-        // pointer holders.
+        // shared pointers.
         m->parent = nullptr;
     }
@@ -66,11 +66,11 @@ class QPDFOutlineObjectHelper: public QPDFObjectHelper
     // Returns the value of /Count as present in the object, or 0 if not present. If count is
     // positive, the outline is open. If negative, it is closed. Either way, the absolute value is
-    // the number descendant items that would be visible if this were open.
+    // the number of descendant items that would be visible if this were open.
     QPDF_DLL
     int getCount();
-    // Returns the title as a UTF-8 string. Returns the empty string if there is no title.
+    // Returns the title as a UTF-8 string. Returns an empty string if there is no title.
     QPDF_DLL
     std::string getTitle();
@@ -56,7 +56,7 @@ class QPDFPageDocumentHelper: public QPDFDocumentHelper
     QPDF_DLL
     void removeUnreferencedResources();
-    // Add new page at the beginning or the end of the current pdf. The newpage parameter may be
+    // Add a new page at the beginning or the end of the current pdf. The newpage parameter may be
     // either a direct object, an indirect object from this QPDF, or an indirect object from another
     // QPDF. If it is a direct object, it will be made indirect. If it is an indirect object from
     // another QPDF, this method will call pushInheritedAttributesToPage on the other file and then
@@ -76,7 +76,7 @@ class QPDFPageDocumentHelper: public QPDFDocumentHelper
     // This method does not have any specific awareness of annotations or form fields, so if you
     // just add a page without thinking about it, you might end up with two pages that share form
     // fields or annotations. While the page may look fine, it will probably not function properly
-    // with regard to interactive features. To work around this, you should called
+    // with regard to interactive features. To work around this, you should call
     // QPDFAcroFormDocumentHelper::fixCopiedAnnotations. A future version of qpdf will likely
     // provide a higher-level interface for copying pages around that will handle document-level
     // constructs in a less error-prone fashion.
@@ -103,11 +103,11 @@ class QPDFWriter
     // Setting Output.  Output may be set only one time.  If you don't use the filename version of
     // the QPDFWriter constructor, you must call exactly one of these methods.
-    // Passing null as filename means write to stdout.  QPDFWriter will create a zero-length output
-    // file upon construction.  If write fails, the empty or partially written file will not be
-    // deleted.  This is by design: sometimes the partial file may be useful for tracking down
+    // Passing nullptr as filename means write to stdout.  QPDFWriter will create a zero-length
+    // output file upon construction.  If write fails, the empty or partially written file will not
+    // be deleted.  This is by design: sometimes the partial file may be useful for tracking down
     // problems.  If your application doesn't want the partially written file to be left behind, you
-    // should delete it the eventual call to write fails.
+    // should delete it if the eventual call to write fails.
     QPDF_DLL
     void setOutputFilename(char const* filename);
@@ -184,8 +184,8 @@ class QPDFWriter
     //
     // qpdf_dl_generalized: This is the default. QPDFWriter will apply LZWDecode, ASCII85Decode,
     // ASCIIHexDecode, and FlateDecode filters on the input. When combined with
-    // setCompressStreams(true), which the default, the effect of this is that streams filtered with
-    // these older and less efficient filters will be recompressed with the Flate filter. By
+    // setCompressStreams(true), which is the default, the effect of this is that streams filtered
+    // with these older and less efficient filters will be recompressed with the Flate filter. By
     // default, as a special case, if a stream is already compressed with FlateDecode and
     // setCompressStreams is enabled, the original compressed data will be preserved. This behavior
     // can be overridden by calling setRecompressFlate(true).
@@ -224,7 +224,7 @@ namespace QUtil
     QPDF_DLL
     time_t get_current_time();
-    // Portable structure representing a point in time with second granularity and time zone offset
+    // Portable structure representing a point in time with second granularity and time zone offset.
     struct QPDFTime
     {
         QPDFTime() = default;
@@ -109,7 +109,7 @@ extern &quot;C&quot; {
 #endif /* QPDF_NO_WCHAR_T */
     /* This function wraps QPDFJob::initializeFromJson. The return value is the same as qpdfjob_run.
-     * If this returns an error, it is invalid to call any other functions this job handle.
+     * If this returns an error, it is invalid to call any other functions using this job handle.
      */
     QPDF_DLL
     int qpdfjob_initialize_from_json(qpdfjob_handle j, char const* json);
@@ -135,7 +135,8 @@ extern &quot;C&quot; {
     /* This function wraps QPDFJob::writeQPDF. It returns the error code that qpdf would return with
      * the equivalent command-line invocation. Exit code values are defined in Constants.h in the
      * qpdf_exit_code_e type. NOTE it is the callers responsibility to clean up the resources
-     * associated qpdf_data object by calling qpdf_cleanup after the call to qpdfjob_write_qpdf.
+     * associated with the qpdf_data object by calling qpdf_cleanup after the call to
+     * qpdfjob_write_qpdf.
      */
     QPDF_DLL
     int qpdfjob_write_qpdf(qpdfjob_handle j, qpdf_data qpdf);
@@ -44,10 +44,10 @@ NNTreeIterator::updateIValue(bool allow_invalid)
     // various cases to ensure we don't introduce that bug in the future, but sadly it's tricky to
     // verify by reasoning about the code that this constraint is always satisfied. Whenever we
     // update what the iterator points to, we should call setItemNumber, which calls this. If we
-    // change what the iterator in some other way, such as replacing a value or removing an item and
-    // making the iterator point at a different item in potentially the same position, we must call
-    // updateIValue as well. These cases are handled, and for good measure, we also call
-    // updateIValue in operator* and operator->.
+    // change what the iterator points to in some other way, such as replacing a value or removing
+    // an item and making the iterator point at a different item in potentially the same position,
+    // we must call updateIValue as well. These cases are handled, and for good measure, we also
+    // call updateIValue in operator* and operator->.
     bool okay = false;
     if ((item_number >= 0) && this->node.isDictionary()) {
@@ -226,7 +226,7 @@ NNTreeIterator::split(QPDFObjectHandle to_split, std::list&lt;PathElement&gt;::iterato
     // Split some node along the path to the item pointed to by this iterator, and adjust the
     // iterator so it points to the same item.
-    // In examples, for simplicity, /Nums is show to just contain numbers instead of pairs. Imagine
+    // In examples, for simplicity, /Nums is shown to just contain numbers instead of pairs. Imagine
     // this tree:
     //
     // root: << /Kids [ A B C D ] >>
@@ -232,7 +232,7 @@ void
 QPDFArgParser::handleArgFileArguments()
 {
     // Support reading arguments from files. Create a new argv. Ensure that argv itself as well as
-    // all its contents are automatically deleted by using shared pointers to back the pointers in
+    // all its contents are automatically deleted by using shared pointers back to the pointers in
     // argv.
     m->new_argv.push_back(QUtil::make_shared_cstr(m->argv[0]));
     for (int i = 1; i < m->argc; ++i) {
@@ -1346,8 +1346,8 @@ QPDFWriter::unparseObject(
         // Make a shallow copy of this object so we can modify it safely without affecting the
         // original. This code has logic to skip certain keys in agreement with prepareFileForWrite
         // and with skip_stream_parameters so that replacing them doesn't leave unreferenced objects
-        // in the output. We can use unsafeShallowCopy here because we are all we are doing is
-        // removing or replacing top-level keys.
+        // in the output. We can use unsafeShallowCopy here because all we are doing is removing or
+        // replacing top-level keys.
         object = object.unsafeShallowCopy();
         // Handle special cases for specific dictionaries.
@@ -1701,7 +1701,7 @@ QPDFWriter::writeObjectStream(QPDFObjectHandle object)
             }
             QPDFObjectHandle obj_to_write = m->pdf.getObject(obj);
             if (obj_to_write.isStream()) {
-                // This condition occurred in a fuzz input. Ideally we should block it at at parse
+                // This condition occurred in a fuzz input. Ideally we should block it at parse
                 // time, but it's not clear to me how to construct a case for this.
                 QTC::TC("qpdf", "QPDFWriter stream in ostream");
                 obj_to_write.warnIfPossible("stream found inside object stream; treating as null");