OpenSystemsDevelopment / qpdf

Commit 549d24ef5a1da1da8f6f74e07995c996d3d8582e

Authored by Peter M. Groen
1 parent 8fa2a58e

Added doxygen tags

Inline Side-by-side
Showing 1 changed file with 343 additions and 288 deletions
include/qpdf/QPDF.hh
  View file @549d24e
... ... @@ -62,75 +62,82 @@ class QPDF
62 62 QPDF_DLL
63 63 static std::shared_ptr<QPDF> create();
64 64  
65   - // Associate a file with a QPDF object and do initial parsing of the file. PDF objects are not
66   - // read until they are needed. A QPDF object may be associated with only one file in its
67   - // lifetime. This method must be called before any methods that potentially ask for information
68   - // about the PDF file are called. Prior to calling this, the only methods that are allowed are
69   - // those that set parameters. If the input file is not encrypted, either a null password or an
70   - // empty password can be used. If the file is encrypted, either the user password or the owner
71   - // password may be supplied. The method setPasswordIsHexKey may be called prior to calling this
72   - // method or any of the other process methods to force the password to be interpreted as a raw
73   - // encryption key. See comments on setPasswordIsHexKey for more information.
  65 + /*! \brief Associate a file with a QPDF object and do initial parsing of the file. PDF objects are not
  66 + * read until they are needed. A QPDF object may be associated with only one file in its
  67 + * lifetime. This method must be called before any methods that potentially ask for information
  68 + * about the PDF file are called. Prior to calling this, the only methods that are allowed are
  69 + * those that set parameters. If the input file is not encrypted, either a null password or an
  70 + * empty password can be used. If the file is encrypted, either the user password or the owner
  71 + * password may be supplied. The method setPasswordIsHexKey may be called prior to calling this
  72 + * method or any of the other process methods to force the password to be interpreted as a raw
  73 + * encryption key. See comments on setPasswordIsHexKey for more information.
  74 + */
74 75 QPDF_DLL
75 76 void processFile(char const* filename, char const* password = nullptr);
76 77  
77   - // Parse a PDF from a stdio FILE*. The FILE must be open in binary mode and must be seekable.
78   - // It may be open read only. This works exactly like processFile except that the PDF file is
79   - // read from an already opened FILE*. If close_file is true, the file will be closed at the
80   - // end. Otherwise, the caller is responsible for closing the file.
  78 + /*! \brief Parse a PDF from a stdio FILE*. The FILE must be open in binary mode and must be seekable.
  79 + * It may be open read only. This works exactly like processFile except that the PDF file is
  80 + * read from an already opened FILE*. If close_file is true, the file will be closed at the
  81 + * end. Otherwise, the caller is responsible for closing the file.
  82 + */
81 83 QPDF_DLL
82 84 void processFile(
83 85 char const* description, FILE* file, bool close_file, char const* password = nullptr);
84 86  
85   - // Parse a PDF file loaded into a memory buffer. This works exactly like processFile except
86   - // that the PDF file is in memory instead of on disk. The description appears in any warning or
87   - // error message in place of the file name. The buffer is owned by the caller and must remain
88   - // valid for the lifetime of the QPDF object.
  87 + /*! \brief Parse a PDF file loaded into a memory buffer. This works exactly like processFile except
  88 + * that the PDF file is in memory instead of on disk. The description appears in any warning or
  89 + * error message in place of the file name. The buffer is owned by the caller and must remain
  90 + * valid for the lifetime of the QPDF object.
  91 + */
89 92 QPDF_DLL
90 93 void processMemoryFile(
91 94 char const* description, char const* buf, size_t length, char const* password = nullptr);
92 95  
93   - // Parse a PDF file loaded from a custom InputSource. If you have your own method of retrieving
94   - // a PDF file, you can subclass InputSource and use this method.
  96 + /*! \brief Parse a PDF file loaded from a custom InputSource. If you have your own method of retrieving
  97 + * a PDF file, you can subclass InputSource and use this method.
  98 + */
95 99 QPDF_DLL
96 100 void processInputSource(std::shared_ptr<InputSource>, char const* password = nullptr);
97 101  
98   - // Create a PDF from an input source that contains JSON as written by writeJSON (or qpdf
99   - // --json-output, version 2 or higher). The JSON must be a complete representation of a PDF. See
100   - // "qpdf JSON" in the manual for details. The input JSON may be arbitrarily large. QPDF does not
101   - // load stream data into memory for more than one stream at a time, even if the stream data is
102   - // specified inline.
  102 + /*! \brief Create a PDF from an input source that contains JSON as written by writeJSON (or qpdf
  103 + * --json-output, version 2 or higher). The JSON must be a complete representation of a PDF. See
  104 + * "qpdf JSON" in the manual for details. The input JSON may be arbitrarily large. QPDF does not
  105 + * load stream data into memory for more than one stream at a time, even if the stream data is
  106 + * specified inline.
  107 + */
103 108 QPDF_DLL
104 109 void createFromJSON(std::string const& json_file);
105 110 QPDF_DLL
106 111 void createFromJSON(std::shared_ptr<InputSource>);
107 112  
108   - // Update a PDF from an input source that contains JSON in the same format as is written by
109   - // writeJSON (or qpdf --json-output, version 2 or higher). Objects in the PDF and not in the
110   - // JSON are not modified. See "qpdf JSON" in the manual for details. As with createFromJSON, the
111   - // input JSON may be arbitrarily large.
  113 + /*! \brief Update a PDF from an input source that contains JSON in the same format as is written by
  114 + * writeJSON (or qpdf --json-output, version 2 or higher). Objects in the PDF and not in the
  115 + * JSON are not modified. See "qpdf JSON" in the manual for details. As with createFromJSON, the
  116 + * input JSON may be arbitrarily large.
  117 + */
112 118 QPDF_DLL
113 119 void updateFromJSON(std::string const& json_file);
114 120 QPDF_DLL
115 121 void updateFromJSON(std::shared_ptr<InputSource>);
116 122  
117   - // Write qpdf JSON format to the pipeline "p". The only supported version is 2. The finish()
118   - // method is not called on the pipeline.
119   - //
120   - // The decode_level parameter controls which streams are uncompressed in the JSON. Use
121   - // qpdf_dl_none to preserve all stream data exactly as it appears in the input. The possible
122   - // values for json_stream_data can be found in qpdf/Constants.h and correspond to the
123   - // --json-stream-data command-line argument. If json_stream_data is qpdf_sj_file, file_prefix
124   - // must be specified. Each stream will be written to a file whose path is constructed by
125   - // appending "-nnn" to file_prefix, where "nnn" is the object number (not zero-filled). If
126   - // wanted_objects is empty, write all objects. Otherwise, write only objects whose keys are in
127   - // wanted_objects. Keys may be either "trailer" or of the form "obj:n n R". Invalid keys are
128   - // ignored. This corresponds to the --json-object command-line argument.
129   - //
130   - // QPDF is efficient with regard to memory when writing, allowing you to write arbitrarily large
131   - // PDF files to a pipeline. You can use a pipeline like Pl_Buffer or Pl_String to capture the
132   - // JSON output in memory, but do so with caution as this will allocate enough memory to hold the
133   - // entire PDF file.
  123 + /*! \brief Write qpdf JSON format to the pipeline "p". The only supported version is 2. The finish()
  124 + * method is not called on the pipeline.
  125 + *
  126 + * The decode_level parameter controls which streams are uncompressed in the JSON. Use
  127 + * qpdf_dl_none to preserve all stream data exactly as it appears in the input. The possible
  128 + * values for json_stream_data can be found in qpdf/Constants.h and correspond to the
  129 + * --json-stream-data command-line argument. If json_stream_data is qpdf_sj_file, file_prefix
  130 + * must be specified. Each stream will be written to a file whose path is constructed by
  131 + * appending "-nnn" to file_prefix, where "nnn" is the object number (not zero-filled). If
  132 + * wanted_objects is empty, write all objects. Otherwise, write only objects whose keys are in
  133 + * wanted_objects. Keys may be either "trailer" or of the form "obj:n n R". Invalid keys are
  134 + * ignored. This corresponds to the --json-object command-line argument.
  135 + *
  136 + * QPDF is efficient with regard to memory when writing, allowing you to write arbitrarily large
  137 + * PDF files to a pipeline. You can use a pipeline like Pl_Buffer or Pl_String to capture the
  138 + * JSON output in memory, but do so with caution as this will allocate enough memory to hold the
  139 + * entire PDF file.
  140 + */
134 141 QPDF_DLL
135 142 void writeJSON(
136 143 int version,
... ... @@ -140,13 +147,14 @@ class QPDF
140 147 std::string const& file_prefix,
141 148 std::set<std::string> wanted_objects);
142 149  
143   - // This version of writeJSON enables writing only the "qpdf" key of an in-progress dictionary.
144   - // If the value of "complete" is true, a complete JSON object containing only the "qpdf" key is
145   - // written to the pipeline. If the value of "complete" is false, the "qpdf" key and its value
146   - // are written to the pipeline assuming that a dictionary is already open. The parameter
147   - // first_key indicates whether this is the first key in an in-progress dictionary. It will be
148   - // set to false by writeJSON. The "qpdf" key and value are written as if at depth 1 in a
149   - // prettified JSON output. Remaining arguments are the same as the above version.
  150 + /*! \brief This version of writeJSON enables writing only the "qpdf" key of an in-progress dictionary.
  151 + * If the value of "complete" is true, a complete JSON object containing only the "qpdf" key is
  152 + * written to the pipeline. If the value of "complete" is false, the "qpdf" key and its value
  153 + * are written to the pipeline assuming that a dictionary is already open. The parameter
  154 + * first_key indicates whether this is the first key in an in-progress dictionary. It will be
  155 + * set to false by writeJSON. The "qpdf" key and value are written as if at depth 1 in a
  156 + * prettified JSON output. Remaining arguments are the same as the above version.
  157 + */
150 158 QPDF_DLL
151 159 void writeJSON(
152 160 int version,
... ... @@ -158,140 +166,155 @@ class QPDF
158 166 std::string const& file_prefix,
159 167 std::set<std::string> wanted_objects);
160 168  
161   - // Close or otherwise release the input source. Once this has been called, no other methods of
162   - // qpdf can be called safely except for getWarnings and anyWarnings(). After this has been
163   - // called, it is safe to perform operations on the input file such as deleting or renaming it.
  169 + /*! \brief Close or otherwise release the input source. Once this has been called, no other methods of
  170 + * qpdf can be called safely except for getWarnings and anyWarnings(). After this has been
  171 + * called, it is safe to perform operations on the input file such as deleting or renaming it.
  172 + */
164 173 QPDF_DLL
165 174 void closeInputSource();
166 175  
167   - // For certain forensic or investigatory purposes, it may sometimes be useful to specify the
168   - // encryption key directly, even though regular PDF applications do not provide a way to do
169   - // this. Calling setPasswordIsHexKey(true) before calling any of the process methods will bypass
170   - // the normal encryption key computation or recovery mechanisms and interpret the bytes in the
171   - // password as a hex-encoded encryption key. Note that we hex-encode the key because it may
172   - // contain null bytes and therefore can't be represented in a char const*.
  176 + /*! \brief For certain forensic or investigatory purposes, it may sometimes be useful to specify the
  177 + * encryption key directly, even though regular PDF applications do not provide a way to do
  178 + * this. Calling setPasswordIsHexKey(true) before calling any of the process methods will bypass
  179 + * the normal encryption key computation or recovery mechanisms and interpret the bytes in the
  180 + * password as a hex-encoded encryption key. Note that we hex-encode the key because it may
  181 + * contain null bytes and therefore can't be represented in a char const*.
  182 + */
173 183 QPDF_DLL
174 184 void setPasswordIsHexKey(bool);
175 185  
176   - // Create a QPDF object for an empty PDF. This PDF has no pages or objects other than a minimal
177   - // trailer, a document catalog, and a /Pages tree containing zero pages. Pages and other
178   - // objects can be added to the file in the normal way, and the trailer and document catalog can
179   - // be mutated. Calling this method is equivalent to calling processFile on an equivalent PDF
180   - // file. See the pdf-create.cc example for a demonstration of how to use this method to create
181   - // a PDF file from scratch.
  186 + /*! \brief Create a QPDF object for an empty PDF. This PDF has no pages or objects other than a minimal
  187 + * trailer, a document catalog, and a /Pages tree containing zero pages. Pages and other
  188 + * objects can be added to the file in the normal way, and the trailer and document catalog can
  189 + * be mutated. Calling this method is equivalent to calling processFile on an equivalent PDF
  190 + * file. See the pdf-create.cc example for a demonstration of how to use this method to create
  191 + * a PDF file from scratch.
  192 + */
182 193 QPDF_DLL
183 194 void emptyPDF();
184 195  
185   - // From 10.1: register a new filter implementation for a specific stream filter. You can add
186   - // your own implementations for new filter types or override existing ones provided by the
187   - // library. Registered stream filters are used for decoding only as you can override encoding
188   - // with stream data providers. For example, you could use this method to add support for one of
189   - // the other filter types by using additional third-party libraries that qpdf does not presently
190   - // use. The standard filters are implemented using QPDFStreamFilter classes.
  196 + /*! \brief From 10.1: register a new filter implementation for a specific stream filter. You can add
  197 + * your own implementations for new filter types or override existing ones provided by the
  198 + * library. Registered stream filters are used for decoding only as you can override encoding
  199 + * with stream data providers. For example, you could use this method to add support for one of
  200 + * the other filter types by using additional third-party libraries that qpdf does not presently
  201 + * use. The standard filters are implemented using QPDFStreamFilter classes.
  202 + */
191 203 QPDF_DLL
192 204 static void registerStreamFilter(
193 205 std::string const& filter_name, std::function<std::shared_ptr<QPDFStreamFilter>()> factory);
194 206  
195 207 // Parameter settings
196 208  
197   - // To capture or redirect output, configure the logger returned by getLogger(). By default, all
198   - // QPDF and QPDFJob objects share the global logger. If you need a private logger for some
199   - // reason, pass a new one to setLogger(). See comments in QPDFLogger.hh for details on
200   - // configuring the logger.
201   - //
202   - // Note that no normal QPDF operations generate output to standard output, so for applications
203   - // that just wish to avoid creating output for warnings and don't call any check functions,
204   - // calling setSuppressWarnings(true) is sufficient.
  209 + /*! \brief To capture or redirect output, configure the logger returned by getLogger(). By default, all
  210 + * QPDF and QPDFJob objects share the global logger. If you need a private logger for some
  211 + * reason, pass a new one to setLogger(). See comments in QPDFLogger.hh for details on
  212 + * configuring the logger.
  213 + *
  214 + * Note that no normal QPDF operations generate output to standard output, so for applications
  215 + * that just wish to avoid creating output for warnings and don't call any check functions,
  216 + * calling setSuppressWarnings(true) is sufficient.
  217 + */
205 218 QPDF_DLL
206 219 std::shared_ptr<QPDFLogger> getLogger();
207 220 QPDF_DLL
208 221 void setLogger(std::shared_ptr<QPDFLogger>);
209 222  
210   - // This deprecated method is the old way to capture output, but it didn't capture all output.
211   - // See comments above for getLogger and setLogger. This will be removed in QPDF 12. For now, it
212   - // configures a private logger, separating this object from the default logger, and calls
213   - // setOutputStreams on that logger. See QPDFLogger.hh for additional details.
  223 + /*! \brief This deprecated method is the old way to capture output, but it didn't capture all output.
  224 + * See comments above for getLogger and setLogger. This will be removed in QPDF 12. For now, it
  225 + * configures a private logger, separating this object from the default logger, and calls
  226 + * setOutputStreams on that logger. See QPDFLogger.hh for additional details.
  227 + */
214 228 [[deprecated("configure logger from getLogger() or call setLogger()")]] QPDF_DLL void
215 229 setOutputStreams(std::ostream* out_stream, std::ostream* err_stream);
216 230  
217   - // If true, ignore any cross-reference streams in a hybrid file (one that contains both
218   - // cross-reference streams and cross-reference tables). This can be useful for testing to
219   - // ensure that a hybrid file would work with an older reader.
  231 + /*! \brief If true, ignore any cross-reference streams in a hybrid file (one that contains both
  232 + * cross-reference streams and cross-reference tables). This can be useful for testing to
  233 + * ensure that a hybrid file would work with an older reader.
  234 + */
220 235 QPDF_DLL
221 236 void setIgnoreXRefStreams(bool);
222 237  
223   - // By default, any warnings are issued to std::cerr or the error stream specified in a call to
224   - // setOutputStreams as they are encountered. If this method is called with a true value,
225   - // reporting of warnings is suppressed. You may still retrieve warnings by calling getWarnings.
  238 + /*! \brief By default, any warnings are issued to std::cerr or the error stream specified in a call to
  239 + * setOutputStreams as they are encountered. If this method is called with a true value,
  240 + * reporting of warnings is suppressed. You may still retrieve warnings by calling getWarnings.
  241 + */
226 242 QPDF_DLL
227 243 void setSuppressWarnings(bool);
228 244  
229   - // Set the maximum number of warnings. A QPDFExc is thrown if the limit is exceeded.
  245 + /*! \brief Set the maximum number of warnings. A QPDFExc is thrown if the limit is exceeded. */
230 246 QPDF_DLL
231 247 void setMaxWarnings(size_t);
232 248  
233   - // By default, QPDF will try to recover if it finds certain types of errors in PDF files. If
234   - // turned off, it will throw an exception on the first such problem it finds without attempting
235   - // recovery.
  249 + /*! \brief By default, QPDF will try to recover if it finds certain types of errors in PDF files. If
  250 + * turned off, it will throw an exception on the first such problem it finds without attempting
  251 + * recovery.
  252 + */
236 253 QPDF_DLL
237 254 void setAttemptRecovery(bool);
238 255  
239   - // Tell other QPDF objects that streams copied from this QPDF need to be fully copied when
240   - // copyForeignObject is called on them. Calling setIgnoreXRefStreams(true) on a QPDF object
241   - // makes it possible for the object and its input source to disappear before streams copied from
242   - // it are written with the destination QPDF object. Confused? Ordinarily, if you are going to
243   - // copy objects from a source QPDF object to a destination QPDF object using copyForeignObject
244   - // or addPage, the source object's input source must stick around until after the destination
245   - // PDF is written. If you call this method on the source QPDF object, it sends a signal to the
246   - // destination object that it must fully copy the stream data when copyForeignObject. It will do
247   - // this by making a copy in RAM. Ordinarily the stream data is copied lazily to avoid
248   - // unnecessary duplication of the stream data. Note that the stream data is copied into RAM only
249   - // once regardless of how many objects the stream is copied into. The result is that, if you
250   - // called setImmediateCopyFrom(true) on a given QPDF object prior to copying any of its streams,
251   - // you do not need to keep it or its input source around after copying its objects to another
252   - // QPDF. This is true even if the source streams use StreamDataProvider. Note that this method
253   - // is called on the QPDF object you are copying FROM, not the one you are copying to. The
254   - // reasoning for this is that there's no reason a given QPDF may not get objects copied to it
255   - // from a variety of other objects, some transient and some not. Since what's relevant is
256   - // whether the source QPDF is transient, the method must be called on the source QPDF, not the
257   - // destination one. This method will make a copy of the stream in RAM, so be sure you have
258   - // enough memory to simultaneously hold all the streams you're copying.
  256 + /*! \brief Tell other QPDF objects that streams copied from this QPDF need to be fully copied when
  257 + * copyForeignObject is called on them. Calling setIgnoreXRefStreams(true) on a QPDF object
  258 + * makes it possible for the object and its input source to disappear before streams copied from
  259 + * it are written with the destination QPDF object. Confused? Ordinarily, if you are going to
  260 + * copy objects from a source QPDF object to a destination QPDF object using copyForeignObject
  261 + * or addPage, the source object's input source must stick around until after the destination
  262 + * PDF is written. If you call this method on the source QPDF object, it sends a signal to the
  263 + * destination object that it must fully copy the stream data when copyForeignObject. It will do
  264 + * this by making a copy in RAM. Ordinarily the stream data is copied lazily to avoid
  265 + * unnecessary duplication of the stream data. Note that the stream data is copied into RAM only
  266 + * once regardless of how many objects the stream is copied into. The result is that, if you
  267 + * called setImmediateCopyFrom(true) on a given QPDF object prior to copying any of its streams,
  268 + * you do not need to keep it or its input source around after copying its objects to another
  269 + * QPDF. This is true even if the source streams use StreamDataProvider. Note that this method
  270 + * is called on the QPDF object you are copying FROM, not the one you are copying to. The
  271 + * reasoning for this is that there's no reason a given QPDF may not get objects copied to it
  272 + * from a variety of other objects, some transient and some not. Since what's relevant is
  273 + * whether the source QPDF is transient, the method must be called on the source QPDF, not the
  274 + * destination one. This method will make a copy of the stream in RAM, so be sure you have
  275 + * enough memory to simultaneously hold all the streams you're copying.
  276 + */
259 277 QPDF_DLL
260 278 void setImmediateCopyFrom(bool);
261 279  
262 280 // Other public methods
263 281  
264   - // Return the list of warnings that have been issued so far and clear the list. This method may
265   - // be called even if processFile throws an exception. Note that if setSuppressWarnings was not
266   - // called or was called with a false value, any warnings retrieved here will have already been
267   - // output.
  282 + /*! \brief Return the list of warnings that have been issued so far and clear the list. This method may
  283 + * be called even if processFile throws an exception. Note that if setSuppressWarnings was not
  284 + * called or was called with a false value, any warnings retrieved here will have already been
  285 + * output.
  286 + */
268 287 QPDF_DLL
269 288 std::vector<QPDFExc> getWarnings();
270 289  
271   - // Indicate whether any warnings have been issued so far. Does not clear the list of warnings.
  290 + /*! \brief Indicate whether any warnings have been issued so far. Does not clear the list of warnings. */
272 291 QPDF_DLL
273 292 bool anyWarnings() const;
274 293  
275   - // Indicate the number of warnings that have been issued since the last call to getWarnings.
276   - // Does not clear the list of warnings.
  294 + /*! \brief Indicate the number of warnings that have been issued since the last call to getWarnings.
  295 + * Does not clear the list of warnings.
  296 + */
277 297 QPDF_DLL
278 298 size_t numWarnings() const;
279 299  
280   - // Return an application-scoped unique ID for this QPDF object. This is not a globally unique
281   - // ID. It is constructed using a timestamp and a random number and is intended to be unique
282   - // among QPDF objects that are created by a single run of an application. While it's very likely
283   - // that these are actually globally unique, it is not recommended to use them for long-term
284   - // purposes.
  300 + /*! \brief Return an application-scoped unique ID for this QPDF object. This is not a globally unique
  301 + * ID. It is constructed using a timestamp and a random number and is intended to be unique
  302 + * among QPDF objects that are created by a single run of an application. While it's very likely
  303 + * that these are actually globally unique, it is not recommended to use them for long-term
  304 + * purposes.
  305 + */
285 306 QPDF_DLL
286 307 unsigned long long getUniqueId() const;
287 308  
288   - // Issue a warning on behalf of this QPDF object. It will be emitted with other warnings,
289   - // following warning suppression rules, and it will be available with getWarnings().
  309 + /*! \brief Issue a warning on behalf of this QPDF object. It will be emitted with other warnings,
  310 + * following warning suppression rules, and it will be available with getWarnings().
  311 + */
290 312 QPDF_DLL
291 313 void warn(QPDFExc const& e);
292   - // Same as above but creates the QPDFExc object using the arguments passed to warn. The filename
293   - // argument to QPDFExc is omitted. This method uses the filename associated with the QPDF
294   - // object.
  314 + /*! \brief Same as above but creates the QPDFExc object using the arguments passed to warn. The filename
  315 + * argument to QPDFExc is omitted. This method uses the filename associated with the QPDF
  316 + * object.
  317 + */
295 318 QPDF_DLL
296 319 void warn(
297 320 qpdf_error_code_e error_code,
... ... @@ -299,13 +322,13 @@ class QPDF
299 322 qpdf_offset_t offset,
300 323 std::string const& message);
301 324  
302   - // Return the filename associated with the QPDF object.
  325 + /*! \brief Return the filename associated with the QPDF object. */
303 326 QPDF_DLL
304 327 std::string getFilename() const;
305   - // Return PDF Version and extension level together as a PDFVersion object
  328 + /*! \brief Return PDF Version and extension level together as a PDFVersion object */
306 329 QPDF_DLL
307 330 PDFVersion getVersionAsPDFVersion();
308   - // Return just the PDF version from the file
  331 + /*! \brief Return just the PDF version from the file */
309 332 QPDF_DLL
310 333 std::string getPDFVersion() const;
311 334 QPDF_DLL
... ... @@ -319,118 +342,128 @@ class QPDF
319 342  
320 343 // Public factory methods
321 344  
322   - // Create a new stream. A subsequent call must be made to replaceStreamData() to provide data
323   - // for the stream. The stream's dictionary may be retrieved by calling getDict(), and the
324   - // resulting dictionary may be modified. Alternatively, you can create a new dictionary and
325   - // call replaceDict to install it.
  345 + /*! \brief Create a new stream. A subsequent call must be made to replaceStreamData() to provide data
  346 + * for the stream. The stream's dictionary may be retrieved by calling getDict(), and the
  347 + * resulting dictionary may be modified. Alternatively, you can create a new dictionary and
  348 + * call replaceDict to install it.
  349 + */
326 350 QPDF_DLL
327 351 QPDFObjectHandle newStream();
328 352  
329   - // Create a new stream. Use the given buffer as the stream data. The stream dictionary's
330   - // /Length key will automatically be set to the size of the data buffer. If additional keys are
331   - // required, the stream's dictionary may be retrieved by calling getDict(), and the resulting
332   - // dictionary may be modified. This method is just a convenient wrapper around the newStream()
333   - // and replaceStreamData(). It is a convenience methods for streams that require no parameters
334   - // beyond the stream length. Note that you don't have to deal with compression yourself if you
335   - // use QPDFWriter. By default, QPDFWriter will automatically compress uncompressed stream data.
336   - // Example programs are provided that illustrate this.
  353 + /*! \brief Create a new stream. Use the given buffer as the stream data. The stream dictionary's
  354 + * /Length key will automatically be set to the size of the data buffer. If additional keys are
  355 + * required, the stream's dictionary may be retrieved by calling getDict(), and the resulting
  356 + * dictionary may be modified. This method is just a convenient wrapper around the newStream()
  357 + * and replaceStreamData(). It is a convenience methods for streams that require no parameters
  358 + * beyond the stream length. Note that you don't have to deal with compression yourself if you
  359 + * use QPDFWriter. By default, QPDFWriter will automatically compress uncompressed stream data.
  360 + * Example programs are provided that illustrate this.
  361 + */
337 362 QPDF_DLL
338 363 QPDFObjectHandle newStream(std::shared_ptr<Buffer> data);
339 364  
340   - // Create new stream with data from string. This method will create a copy of the data rather
341   - // than using the user-provided buffer as in the std::shared_ptr<Buffer> version of newStream.
  365 + /*! \brief Create new stream with data from string. This method will create a copy of the data rather
  366 + * than using the user-provided buffer as in the std::shared_ptr<Buffer> version of newStream.
  367 + */
342 368 QPDF_DLL
343 369 QPDFObjectHandle newStream(std::string const& data);
344 370  
345   - // A reserved object is a special sentinel used for qpdf to reserve a spot for an object that is
346   - // going to be added to the QPDF object. Normally you don't have to use this type since you can
347   - // just call QPDF::makeIndirectObject. However, in some cases, if you have to create objects
348   - // with circular references, you may need to create a reserved object so that you can have a
349   - // reference to it and then replace the object later. Reserved objects have the special
350   - // property that they can't be resolved to direct objects. This makes it possible to replace a
351   - // reserved object with a new object while preserving existing references to them. When you are
352   - // ready to replace a reserved object with its replacement, use QPDF::replaceReserved for this
353   - // purpose rather than the more general QPDF::replaceObject. It is an error to try to write a
354   - // QPDF with QPDFWriter if it has any reserved objects in it.
  371 + /*! \brief A reserved object is a special sentinel used for qpdf to reserve a spot for an object that is
  372 + * going to be added to the QPDF object. Normally you don't have to use this type since you can
  373 + * just call QPDF::makeIndirectObject. However, in some cases, if you have to create objects
  374 + * with circular references, you may need to create a reserved object so that you can have a
  375 + * reference to it and then replace the object later. Reserved objects have the special
  376 + * property that they can't be resolved to direct objects. This makes it possible to replace a
  377 + * reserved object with a new object while preserving existing references to them. When you are
  378 + * ready to replace a reserved object with its replacement, use QPDF::replaceReserved for this
  379 + * purpose rather than the more general QPDF::replaceObject. It is an error to try to write a
  380 + * QPDF with QPDFWriter if it has any reserved objects in it.
  381 + */
355 382 QPDF_DLL
356 383 QPDFObjectHandle newReserved();
357 384 QPDF_DLL
358 385 QPDFObjectHandle newIndirectNull();
359 386  
360   - // Install this object handle as an indirect object and return an indirect reference to it.
  387 + /*! \brief Install this object handle as an indirect object and return an indirect reference to it. */
361 388 QPDF_DLL
362 389 QPDFObjectHandle makeIndirectObject(QPDFObjectHandle);
363 390  
364   - // Retrieve an object by object ID and generation. Returns an indirect reference to it. The
365   - // getObject() methods were added for qpdf 11.
  391 + /*! \brief Retrieve an object by object ID and generation. Returns an indirect reference to it. The
  392 + * getObject() methods were added for qpdf 11.
  393 + */
366 394 QPDF_DLL
367 395 QPDFObjectHandle getObject(QPDFObjGen);
368 396 QPDF_DLL
369 397 QPDFObjectHandle getObject(int objid, int generation);
370   - // These are older methods, but there is no intention to deprecate
371   - // them.
  398 + /*! \brief These are older methods, but there is no intention to deprecate
  399 + * them.
  400 + */
372 401 QPDF_DLL
373 402 QPDFObjectHandle getObjectByObjGen(QPDFObjGen);
374 403 QPDF_DLL
375 404 QPDFObjectHandle getObjectByID(int objid, int generation);
376 405  
377   - // Replace the object with the given object id with the given object. The object handle passed
378   - // in must be a direct object, though it may contain references to other indirect objects within
379   - // it. Prior to qpdf 10.2.1, after calling this method, existing QPDFObjectHandle instances that
380   - // pointed to the original object still pointed to the original object, resulting in confusing
381   - // and incorrect behavior. This was fixed in 10.2.1, so existing QPDFObjectHandle objects will
382   - // start pointing to the newly replaced object. Note that replacing an object with
383   - // QPDFObjectHandle::newNull() effectively removes the object from the file since a non-existent
384   - // object is treated as a null object. To replace a reserved object, call replaceReserved
385   - // instead.
  406 + /*! \brief Replace the object with the given object id with the given object. The object handle passed
  407 + * in must be a direct object, though it may contain references to other indirect objects within
  408 + * it. Prior to qpdf 10.2.1, after calling this method, existing QPDFObjectHandle instances that
  409 + * pointed to the original object still pointed to the original object, resulting in confusing
  410 + * and incorrect behavior. This was fixed in 10.2.1, so existing QPDFObjectHandle objects will
  411 + * start pointing to the newly replaced object. Note that replacing an object with
  412 + * QPDFObjectHandle::newNull() effectively removes the object from the file since a non-existent
  413 + * object is treated as a null object. To replace a reserved object, call replaceReserved
  414 + * instead.
  415 + */
386 416 QPDF_DLL
387 417 void replaceObject(QPDFObjGen og, QPDFObjectHandle);
388 418 QPDF_DLL
389 419 void replaceObject(int objid, int generation, QPDFObjectHandle);
390 420  
391   - // Swap two objects given by ID. Prior to qpdf 10.2.1, existing QPDFObjectHandle instances that
392   - // reference them objects not notice the swap, but this was fixed in 10.2.1.
  421 + /*! \brief Swap two objects given by ID. Prior to qpdf 10.2.1, existing QPDFObjectHandle instances that
  422 + * reference them objects not notice the swap, but this was fixed in 10.2.1.
  423 + */
393 424 QPDF_DLL
394 425 void swapObjects(QPDFObjGen og1, QPDFObjGen og2);
395 426 QPDF_DLL
396 427 void swapObjects(int objid1, int generation1, int objid2, int generation2);
397 428  
398   - // Replace a reserved object. This is a wrapper around replaceObject but it guarantees that the
399   - // underlying object is a reserved object or a null object. After this call, reserved will
400   - // be a reference to replacement.
  429 + /*! \brief Replace a reserved object. This is a wrapper around replaceObject but it guarantees that the
  430 + * underlying object is a reserved object or a null object. After this call, reserved will
  431 + * be a reference to replacement.
  432 + */
401 433 QPDF_DLL
402 434 void replaceReserved(QPDFObjectHandle reserved, QPDFObjectHandle replacement);
403 435  
404   - // Copy an object from another QPDF to this one. Starting with qpdf version 8.3.0, it is no
405   - // longer necessary to keep the original QPDF around after the call to copyForeignObject as long
406   - // as the source of any copied stream data is still available. Usually this means you just have
407   - // to keep the input file around, not the QPDF object. The exception to this is if you copy a
408   - // stream that gets its data from a QPDFObjectHandle::StreamDataProvider. In this case only, the
409   - // original stream's QPDF object must stick around because the QPDF object is itself the source
410   - // of the original stream data. For a more in-depth discussion, please see the TODO file.
411   - // Starting in 8.4.0, you can call setImmediateCopyFrom(true) on the SOURCE QPDF object (the one
412   - // you're copying FROM). If you do this prior to copying any of its objects, then neither the
413   - // source QPDF object nor its input source needs to stick around at all regardless of the
414   - // source. The cost is that the stream data is copied into RAM at the time copyForeignObject is
415   - // called. See setImmediateCopyFrom for more information.
416   - //
417   - // The return value of this method is an indirect reference to the copied object in this file.
418   - // This method is intended to be used to copy non-page objects. To copy page objects, pass the
419   - // foreign page object directly to addPage (or addPageAt). If you copy objects that contain
420   - // references to pages, you should copy the pages first using addPage(At). Otherwise references
421   - // to the pages that have not been copied will be replaced with nulls. It is possible to use
422   - // copyForeignObject on page objects if you are not going to use them as pages. Doing so copies
423   - // the object normally but does not update the page structure. For example, it is a valid use
424   - // case to use copyForeignObject for a page that you are going to turn into a form XObject,
425   - // though you can also use QPDFPageObjectHelper::getFormXObjectForPage for that purpose.
426   - //
427   - // When copying objects with this method, object structure will be preserved, so all indirectly
428   - // referenced indirect objects will be copied as well. This includes any circular references
429   - // that may exist. The QPDF object keeps a record of what has already been copied, so shared
430   - // objects will not be copied multiple times. This also means that if you mutate an object that
431   - // has already been copied and try to copy it again, it won't work since the modified object
432   - // will not be recopied. Therefore, you should do all mutation on the original file that you
433   - // are going to do before you start copying its objects to a new file.
  436 + /*! \brief Copy an object from another QPDF to this one. Starting with qpdf version 8.3.0, it is no
  437 + * longer necessary to keep the original QPDF around after the call to copyForeignObject as long
  438 + * as the source of any copied stream data is still available. Usually this means you just have
  439 + * to keep the input file around, not the QPDF object. The exception to this is if you copy a
  440 + * stream that gets its data from a QPDFObjectHandle::StreamDataProvider. In this case only, the
  441 + * original stream's QPDF object must stick around because the QPDF object is itself the source
  442 + * of the original stream data. For a more in-depth discussion, please see the TODO file.
  443 + * Starting in 8.4.0, you can call setImmediateCopyFrom(true) on the SOURCE QPDF object (the one
  444 + * you're copying FROM). If you do this prior to copying any of its objects, then neither the
  445 + * source QPDF object nor its input source needs to stick around at all regardless of the
  446 + * source. The cost is that the stream data is copied into RAM at the time copyForeignObject is
  447 + * called. See setImmediateCopyFrom for more information.
  448 + *
  449 + * The return value of this method is an indirect reference to the copied object in this file.
  450 + * This method is intended to be used to copy non-page objects. To copy page objects, pass the
  451 + * foreign page object directly to addPage (or addPageAt). If you copy objects that contain
  452 + * references to pages, you should copy the pages first using addPage(At). Otherwise references
  453 + * to the pages that have not been copied will be replaced with nulls. It is possible to use
  454 + * copyForeignObject on page objects if you are not going to use them as pages. Doing so copies
  455 + * the object normally but does not update the page structure. For example, it is a valid use
  456 + * case to use copyForeignObject for a page that you are going to turn into a form XObject,
  457 + * though you can also use QPDFPageObjectHelper::getFormXObjectForPage for that purpose.
  458 + *
  459 + * When copying objects with this method, object structure will be preserved, so all indirectly
  460 + * referenced indirect objects will be copied as well. This includes any circular references
  461 + * that may exist. The QPDF object keeps a record of what has already been copied, so shared
  462 + * objects will not be copied multiple times. This also means that if you mutate an object that
  463 + * has already been copied and try to copy it again, it won't work since the modified object
  464 + * will not be recopied. Therefore, you should do all mutation on the original file that you
  465 + * are going to do before you start copying its objects to a new file.
  466 + */
434 467 QPDF_DLL
435 468 QPDFObjectHandle copyForeignObject(QPDFObjectHandle foreign);
436 469  
... ... @@ -438,8 +471,9 @@ class QPDF
438 471  
439 472 enum encryption_method_e { e_none, e_unknown, e_rc4, e_aes, e_aesv3 };
440 473  
441   - // To be removed from the public API in qpdf 13. See
442   - // <https:manual.qpdf.org/release-notes.html#r12-3-0-deprecate>.
  474 + /*! \brief To be removed from the public API in qpdf 13. See
  475 + * <https:manual.qpdf.org/release-notes.html#r12-3-0-deprecate>.
  476 + */
443 477 class EncryptionData
444 478 {
445 479 public:
... ... @@ -548,8 +582,9 @@ class QPDF
548 582 QPDF_DLL
549 583 bool allowModifyAll();
550 584  
551   - // Helper function to trim padding from user password. Calling trim_user_password on the result
552   - // of getPaddedUserPassword gives getTrimmedUserPassword's result.
  585 + /*! \brief Helper function to trim padding from user password. Calling trim_user_password on the result
  586 + * of getPaddedUserPassword gives getTrimmedUserPassword's result.
  587 + */
553 588 QPDF_DLL
554 589 static void trim_user_password(std::string& user_password);
555 590 QPDF_DLL
... ... @@ -561,7 +596,7 @@ class QPDF
561 596 int encryption_V,
562 597 int encryption_R);
563 598  
564   - // To be removed in qpdf 13. See <https:manual.qpdf.org/release-notes.html#r12-3-0-deprecate>.
  599 + /*! \brief To be removed in qpdf 13. See <https:manual.qpdf.org/release-notes.html#r12-3-0-deprecate>. */
565 600 [[deprecated("to be removed in qpdf 13")]]
566 601 QPDF_DLL static std::string
567 602 compute_encryption_key(std::string const& password, EncryptionData const& data);
... ... @@ -594,94 +629,108 @@ class QPDF
594 629 std::string& OE,
595 630 std::string& UE,
596 631 std::string& Perms);
597   - // Return the full user password as stored in the PDF file. For files encrypted with 40-bit or
598   - // 128-bit keys, the user password can be recovered when the file is opened using the owner
599   - // password. This is not possible with newer encryption formats. If you are attempting to
600   - // recover the user password in a user-presentable form, call getTrimmedUserPassword() instead.
  632 +
  633 + /*! \brief Return the full user password as stored in the PDF file. For files encrypted with 40-bit or
  634 + * 128-bit keys, the user password can be recovered when the file is opened using the owner
  635 + * password. This is not possible with newer encryption formats. If you are attempting to
  636 + * recover the user password in a user-presentable form, call getTrimmedUserPassword() instead.
  637 + */
601 638 QPDF_DLL
602 639 std::string const& getPaddedUserPassword() const;
603   - // Return human-readable form of user password subject to same limitations as
604   - // getPaddedUserPassword().
  640 +
  641 + /*! \brief Return human-readable form of user password subject to same limitations as
  642 + * getPaddedUserPassword().
  643 + */
605 644 QPDF_DLL
606 645 std::string getTrimmedUserPassword() const;
607   - // Return the previously computed or retrieved encryption key for this file
  646 +
  647 + /*! \brief Return the previously computed or retrieved encryption key for this file */
608 648 QPDF_DLL
609 649 std::string getEncryptionKey() const;
610   - // Remove security restrictions associated with digitally signed files. From qpdf 11.7.0, this
611   - // is called by QPDFAcroFormDocumentHelper::disableDigitalSignatures and is more useful when
612   - // called from there than when just called by itself.
  650 + /*! \brief Remove security restrictions associated with digitally signed files. From qpdf 11.7.0, this
  651 + * is called by QPDFAcroFormDocumentHelper::disableDigitalSignatures and is more useful when
  652 + * called from there than when just called by itself.
  653 + */
613 654 QPDF_DLL
614 655 void removeSecurityRestrictions();
615 656  
616 657 // Linearization support
617 658  
618   - // Returns true iff the file starts with a linearization parameter dictionary. Does no
619   - // additional validation.
  659 + /*! \brief Returns true iff the file starts with a linearization parameter dictionary. Does no
  660 + * additional validation.
  661 + */
620 662 QPDF_DLL
621 663 bool isLinearized();
622 664  
623   - // Performs various sanity checks on a linearized file. Return true if no errors or warnings.
624   - // Otherwise, return false and output errors and warnings to the default output stream
625   - // (std::cout or whatever is configured in the logger). It is recommended for linearization
626   - // errors to be treated as warnings.
  665 + /*! \brief Performs various sanity checks on a linearized file. Return true if no errors or warnings.
  666 + * Otherwise, return false and output errors and warnings to the default output stream
  667 + * (std::cout or whatever is configured in the logger). It is recommended for linearization
  668 + * errors to be treated as warnings.
  669 + */
627 670 QPDF_DLL
628 671 bool checkLinearization();
629 672  
630   - // Calls checkLinearization() and, if possible, prints normalized contents of some of the hints
631   - // tables to the default output stream. Normalization includes adding min values to delta values
632   - // and adjusting offsets based on the location and size of the primary hint stream.
  673 + /*! \brief Calls checkLinearization() and, if possible, prints normalized contents of some of the hints
  674 + * tables to the default output stream. Normalization includes adding min values to delta values
  675 + * and adjusting offsets based on the location and size of the primary hint stream.
  676 + */
633 677 QPDF_DLL
634 678 void showLinearizationData();
635 679  
636   - // Shows the contents of the cross-reference table
  680 + /*! \brief Shows the contents of the cross-reference table. */
637 681 QPDF_DLL
638 682 void showXRefTable();
639 683  
640   - // Starting from qpdf 11.0 user code should not need to call this method. Before 11.0 this
641   - // method was used to detect all indirect references to objects that don't exist and resolve
642   - // them by replacing them with null, which is how the PDF spec says to interpret such dangling
643   - // references. This method is called automatically when you try to add any new objects, if you
644   - // call getAllObjects, and before a file is written. The qpdf object caches whether it has run
645   - // this to avoid running it multiple times. Before 11.2.1 you could pass true to force it to run
646   - // again if you had explicitly added new objects that may have additional dangling references.
  684 + /*! \brief Starting from qpdf 11.0 user code should not need to call this method. Before 11.0 this
  685 + * method was used to detect all indirect references to objects that don't exist and resolve
  686 + * them by replacing them with null, which is how the PDF spec says to interpret such dangling
  687 + * references. This method is called automatically when you try to add any new objects, if you
  688 + * call getAllObjects, and before a file is written. The qpdf object caches whether it has run
  689 + * this to avoid running it multiple times. Before 11.2.1 you could pass true to force it to run
  690 + * again if you had explicitly added new objects that may have additional dangling references.
  691 + *
647 692 QPDF_DLL
648 693 void fixDanglingReferences(bool force = false);
649 694  
650   - // Return the approximate number of indirect objects. It is/ approximate because not all objects
651   - // in the file are preserved in all cases, and gaps in object numbering are not preserved.
  695 + /*! \brief Return the approximate number of indirect objects. It is/ approximate because not all objects
  696 + * in the file are preserved in all cases, and gaps in object numbering are not preserved.
  697 + */
652 698 QPDF_DLL
653 699 size_t getObjectCount();
654 700  
655   - // Returns a list of indirect objects for every object in the xref table. Useful for discovering
656   - // objects that are not otherwise referenced.
  701 + /*! \brief Returns a list of indirect objects for every object in the xref table. Useful for discovering
  702 + * objects that are not otherwise referenced.
  703 + */
657 704 QPDF_DLL
658 705 std::vector<QPDFObjectHandle> getAllObjects();
659 706  
660 707 // Optimization support -- see doc/optimization. Implemented in QPDF_optimization.cc
661 708  
662   - // The object_stream_data map maps from a "compressed" object to the object stream that contains
663   - // it. This enables optimize to populate the object <-> user maps with only uncompressed
664   - // objects. If allow_changes is false, an exception will be thrown if any changes are made
665   - // during the optimization process. This is available so that the test suite can make sure that
666   - // a linearized file is already optimized. When called in this way, optimize() still populates
667   - // the object <-> user maps. The optional skip_stream_parameters parameter, if present, is
668   - // called for each stream object. The function should return 2 if optimization should discard
669   - // /Length, /Filter, and /DecodeParms; 1 if it should discard /Length, and 0 if it should
670   - // preserve all keys. This is used by QPDFWriter to avoid creation of dangling objects for
671   - // stream dictionary keys it will be regenerating.
  709 + /*! \brief The object_stream_data map maps from a "compressed" object to the object stream that contains
  710 + * it. This enables optimize to populate the object <-> user maps with only uncompressed
  711 + * objects. If allow_changes is false, an exception will be thrown if any changes are made
  712 + * during the optimization process. This is available so that the test suite can make sure that
  713 + * a linearized file is already optimized. When called in this way, optimize() still populates
  714 + * the object <-> user maps. The optional skip_stream_parameters parameter, if present, is
  715 + * called for each stream object. The function should return 2 if optimization should discard
  716 + * /Length, /Filter, and /DecodeParms; 1 if it should discard /Length, and 0 if it should
  717 + * preserve all keys. This is used by QPDFWriter to avoid creation of dangling objects for
  718 + * stream dictionary keys it will be regenerating.
  719 + */
672 720 [[deprecated("Unused - see release notes for qpdf 12.1.0")]] QPDF_DLL void optimize(
673 721 std::map<int, int> const& object_stream_data,
674 722 bool allow_changes = true,
675 723 std::function<int(QPDFObjectHandle&)> skip_stream_parameters = nullptr);
676 724  
677   - // Traverse page tree return all /Page objects. It also detects and resolves cases in which the
678   - // same /Page object is duplicated. For efficiency, this method returns a const reference to an
679   - // internal vector of pages. Calls to addPage, addPageAt, and removePage safely update this, but
680   - // direct manipulation of the pages tree or pushing inheritable objects to the page level may
681   - // invalidate it. See comments for updateAllPagesCache() for additional notes. Newer code should
682   - // use QPDFPageDocumentHelper::getAllPages instead. The decision to expose this internal cache
683   - // was arguably incorrect, but it is being left here for compatibility. It is, however,
684   - // completely safe to use this for files that you are not modifying.
  725 + /*! \brief Traverse page tree return all /Page objects. It also detects and resolves cases in which the
  726 + * same /Page object is duplicated. For efficiency, this method returns a const reference to an
  727 + * internal vector of pages. Calls to addPage, addPageAt, and removePage safely update this, but
  728 + * direct manipulation of the pages tree or pushing inheritable objects to the page level may
  729 + * invalidate it. See comments for updateAllPagesCache() for additional notes. Newer code should
  730 + * use QPDFPageDocumentHelper::getAllPages instead. The decision to expose this internal cache
  731 + * was arguably incorrect, but it is being left here for compatibility. It is, however,
  732 + * completely safe to use this for files that you are not modifying.
  733 + */
685 734 QPDF_DLL
686 735 std::vector<QPDFObjectHandle> const& getAllPages();
687 736  
... ... @@ -690,32 +739,35 @@ class QPDF
690 739 QPDF_DLL
691 740 bool everPushedInheritedAttributesToPages() const;
692 741  
693   - // These methods, given a page object or its object/generation number, returns the 0-based index
694   - // into the array returned by getAllPages() for that page. An exception is thrown if the page is
695   - // not found.
  742 + /*! \brief These methods, given a page object or its object/generation number, returns the 0-based index
  743 + * into the array returned by getAllPages() for that page. An exception is thrown if the page is
  744 + * not found.
  745 + */
696 746 QPDF_DLL
697 747 int findPage(QPDFObjGen og);
698 748 QPDF_DLL
699 749 int findPage(QPDFObjectHandle& page);
700 750  
701   - // This method synchronizes QPDF's cache of the page structure with the actual /Pages tree. If
702   - // you restrict changes to the /Pages tree, including addition, removal, or replacement of pages
703   - // or changes to any /Pages objects, to calls to these page handling APIs, you never need to
704   - // call this method. If you modify /Pages structures directly, you must call this method
705   - // afterwards. This method updates the internal list of pages, so after calling this method,
706   - // any previous references returned by getAllPages() will be valid again. It also resets any
707   - // state about having pushed inherited attributes in /Pages objects down to the pages, so if you
708   - // add any inheritable attributes to a /Pages object, you should also call this method.
  751 + /*! \brief This method synchronizes QPDF's cache of the page structure with the actual /Pages tree. If
  752 + * you restrict changes to the /Pages tree, including addition, removal, or replacement of pages
  753 + * or changes to any /Pages objects, to calls to these page handling APIs, you never need to
  754 + * call this method. If you modify /Pages structures directly, you must call this method
  755 + * afterwards. This method updates the internal list of pages, so after calling this method,
  756 + * any previous references returned by getAllPages() will be valid again. It also resets any
  757 + * state about having pushed inherited attributes in /Pages objects down to the pages, so if you
  758 + * add any inheritable attributes to a /Pages object, you should also call this method.
  759 + */
709 760 QPDF_DLL
710 761 void updateAllPagesCache();
711 762  
712   - // Legacy handling API. These methods are not going anywhere, and you should feel free to
713   - // continue using them if it simplifies your code. Newer code should make use of
714   - // QPDFPageDocumentHelper instead as future page handling methods will be added there. The
715   - // functionality and specification of these legacy methods is identical to the identically named
716   - // methods there, except that these versions use QPDFObjectHandle instead of
717   - // QPDFPageObjectHelper, so please see comments in that file for descriptions. There are
718   - // subtleties you need to know about, so please look at the comments there.
  763 + /*! \brief Legacy handling API. These methods are not going anywhere, and you should feel free to
  764 + * continue using them if it simplifies your code. Newer code should make use of
  765 + * QPDFPageDocumentHelper instead as future page handling methods will be added there. The
  766 + * functionality and specification of these legacy methods is identical to the identically named
  767 + * methods there, except that these versions use QPDFObjectHandle instead of
  768 + * QPDFPageObjectHelper, so please see comments in that file for descriptions. There are
  769 + * subtleties you need to know about, so please look at the comments there.
  770 + */
719 771 QPDF_DLL
720 772 void pushInheritedAttributesToPage();
721 773 QPDF_DLL
... ... @@ -736,10 +788,11 @@ class QPDF
736 788 static bool test_json_validators();
737 789  
738 790 private:
739   - // It has never been safe to copy QPDF objects as there is code in the library that assumes
740   - // there are no copies of a QPDF object. Copying QPDF objects was not prevented by the API until
741   - // qpdf 11. If you have been copying QPDF objects, use std::shared_ptr<QPDF> instead. From qpdf
742   - // 11, you can use QPDF::create to create them.
  791 + /*! \brief It has never been safe to copy QPDF objects as there is code in the library that assumes
  792 + * there are no copies of a QPDF object. Copying QPDF objects was not prevented by the API until
  793 + * qpdf 11. If you have been copying QPDF objects, use std::shared_ptr<QPDF> instead. From qpdf
  794 + * 11, you can use QPDF::create to create them.
  795 + */
743 796 QPDF(QPDF const&) = delete;
744 797 QPDF& operator=(QPDF const&) = delete;
745 798  
... ... @@ -753,7 +806,7 @@ class QPDF
753 806  
754 807 void removeObject(QPDFObjGen og);
755 808  
756   - // Calls finish() on the pipeline when done but does not delete it
  809 + /*! \brief Calls finish() on the pipeline when done but does not delete it */
757 810 bool pipeStreamData(
758 811 QPDFObjGen og,
759 812 qpdf_offset_t offset,
... ... @@ -763,6 +816,7 @@ class QPDF
763 816 Pipeline* pipeline,
764 817 bool suppress_warnings,
765 818 bool will_retry);
  819 +
766 820 static bool pipeStreamData(
767 821 std::shared_ptr<QPDF::EncryptionParameters> encp,
768 822 std::shared_ptr<InputSource> file,
... ... @@ -776,7 +830,7 @@ class QPDF
776 830 bool suppress_warnings,
777 831 bool will_retry);
778 832  
779   - // methods to support encryption -- implemented in QPDF_encryption.cc
  833 + /*! \brief methods to support encryption -- implemented in QPDF_encryption.cc */
780 834 void initializeEncryption();
781 835 static std::string
782 836 getKeyForObject(std::shared_ptr<EncryptionParameters> encp, QPDFObjGen og, bool use_aes);
... ... @@ -796,8 +850,9 @@ class QPDF
796 850  
797 851 class Members;
798 852  
799   - // Keep all member variables inside the Members object, which we dynamically allocate. This
800   - // makes it possible to add new private members without breaking binary compatibility.
  853 + /*! \brief Keep all member variables inside the Members object, which we dynamically allocate. This
  854 + * makes it possible to add new private members without breaking binary compatibility.
  855 + */
801 856 std::unique_ptr<Members> m;
802 857 };
803 858  
... ...