Hi all,
I have attached a patch with clarifications, formatting
and typo fixes to PdfStream.h and PdfFilter.h (please
review them, if accepted, please apply). I only post this
late because I had problems with my Internet access, I'm sorry.
Best regards, mabri
Index: src/base/PdfStream.h
===================================================================
--- src/base/PdfStream.h (revision 1676)
+++ src/base/PdfStream.h (working copy)
@@ -81,7 +81,7 @@
/** Set a binary buffer as stream data.
*
- * Use PdfFilterFactory::CreateFilterList if you want to use the contents
+ * Use PdfFilterFactory::CreateFilterList() if you want to use the contents
* of the stream dictionary's existing filter key.
*
* \param szBuffer buffer containing the stream data
@@ -91,7 +91,7 @@
void Set( const char* szBuffer, pdf_long lLen, const TVecFilters & vecFilters );
/** Set a binary buffer as stream data.
- * All data will be flate encoded.
+ * All data will be Flate-encoded.
*
* \param szBuffer buffer containing the stream data
* \param lLen length of the buffer
@@ -99,7 +99,7 @@
void Set( const char* szBuffer, pdf_long lLen );
/** Set a binary buffer whose contents are read from a PdfInputStream
- * All data will be flate encoded.
+ * All data will be Flate-encoded.
*
* \param pStream read stream contents from this PdfInputStream
*/
@@ -107,7 +107,7 @@
/** Set a binary buffer whose contents are read from a PdfInputStream
*
- * Use PdfFilterFactory::CreateFilterList if you want to use the contents
+ * Use PdfFilterFactory::CreateFilterList() if you want to use the contents
* of the stream dictionary's existing filter key.
*
* \param pStream read stream contents from this PdfInputStream
@@ -115,21 +115,23 @@
*/
void Set( PdfInputStream* pStream, const TVecFilters & vecFilters );
- /** Set a null-terminated char* buffer as the streams contents.
+ /** Set a null-terminated char* buffer as the stream's contents.
*
* The string will be copied into a newly allocated buffer.
- * \param pszString a zero terminated string buffer containing only ASCII text data
+ * \param pszString a zero terminated string buffer containing only
+ * ASCII text data
*/
inline void Set( const char* pszString );
- /** Sets raw data for this filter which is read from an input stream.
+ /** Sets raw data for this stream which is read from an input stream.
* This method does neither encode nor decode the read data.
- * The filters of the object are not modified and the data is expected to be
- * encoded as stated by the /Filters key in the streams object.
+ * The filters of the object are not modified and the data is expected
+ * encoded as stated by the /Filters key in the stream's object.
*
* \param pStream read data from this input stream
- * \param lLen read excactly lLen bytes from the input stream
- * if lLen = -1 read until the end of the input stream was reached.
+ * \param lLen read exactly lLen bytes from the input stream,
+ * if lLen = -1 read until the end of the input stream
+ * was reached.
*/
void SetRawData( PdfInputStream* pStream, pdf_long lLen = -1 );
@@ -136,10 +138,10 @@
/** Start appending data to this stream.
*
* This method has to be called before any of the append methods.
- * All appended data will be flate decoded!
+ * All appended data will be Flate-encoded.
*
- * \param bClearExisting if true any existing stream contents will be
- * cleared.
+ * \param bClearExisting if true any existing stream contents will
+ * be cleared.
*
* \see Append
* \see EndAppend
@@ -149,13 +151,14 @@
/** Start appending data to this stream.
* This method has to be called before any of the append methods.
*
- * Use PdfFilterFactory::CreateFilterList if you want to use the contents
+ * Use PdfFilterFactory::CreateFilterList() if you want to use the contents
* of the stream dictionary's existing filter key.
*
* \param vecFilters a list of filters to use when appending data
- * \param bClearExisting if true any existing stream contents will be cleared.
+ * \param bClearExisting if true any existing stream contents will
+ be cleared.
* \param bDeleteFilters if true existing filter keys are deleted if an
- * empty list of filters is passed (required for SetRawData)
+ * empty list of filters is passed (required for SetRawData())
*
* \see Append
* \see EndAppend
@@ -164,7 +167,7 @@
/** Append a binary buffer to the current stream contents.
*
- * Make sure BeginAppend has been called before.
+ * Make sure BeginAppend() has been called before.
*
* \param pszString a buffer
* \param lLen length of the buffer
@@ -176,9 +179,10 @@
/** Append a null-terminated string to the current stream contents.
*
- * Make sure BeginAppend has been called before.
+ * Make sure BeginAppend() has been called before.
*
- * \param pszString a zero terminated string buffer containing only ASCII text data
+ * \param pszString a zero-terminated string buffer containing only
+ * ASCII text data
*
* \see BeginAppend
* \see EndAppend
@@ -187,9 +191,9 @@
/** Append to the current stream contents.
*
- * Make sure BeginAppend has been called before.
+ * Make sure BeginAppend() has been called before.
*
- * \param sString a std::string containing ASCII text data
+ * \param sString a std::string containing only ASCII text data
*
* \see BeginAppend
* \see EndAppend
@@ -206,8 +210,8 @@
/**
* \returns true if code is between BeginAppend()
- * and EndAppend() at the moment. I.e.
- * it is save to call EndAppend now.
+ * and EndAppend() at the moment, i.e. it
+ * is safe to call EndAppend() now.
*
* \see BeginAppend
* \see Append
@@ -214,16 +218,16 @@
*/
inline bool IsAppending() const;
- /** Get the stream's length with all filters applied (eg if the stream is
- * Flate compressed, the length of the compressed data stream).
+ /** Get the stream's length with all filters applied (e.g. if the stream is
+ * Flate-compressed, the length of the compressed data stream).
*
* \returns the length of the internal buffer
*/
virtual pdf_long GetLength() const = 0;
- /** Get a malloced buffer of the current stream.
+ /** Get a malloc()'d buffer of the current stream.
* No filters will be applied to the buffer, so
- * if the stream is Flate compressed the compressed copy
+ * if the stream is Flate-compressed the compressed copy
* will be returned.
*
* The caller has to free() the buffer.
@@ -239,9 +243,9 @@
*/
virtual void GetCopy( PdfOutputStream* pStream ) const = 0;
- /** Get a malloced buffer of the current stream which has been
+ /** Get a malloc()'d buffer of the current stream which has been
* filtered by all filters as specified in the dictionary's
- * /Filter key. For example, if the stream is Flate compressed,
+ * /Filter key. For example, if the stream is Flate-compressed,
* the buffer returned from this method will have been decompressed.
*
* The caller has to free() the buffer.
@@ -264,12 +268,12 @@
const PdfStream & operator=( const PdfStream & rhs );
protected:
- /** Required for the GetFilteredCopy implementation
+ /** Required for the GetFilteredCopy() implementation
* \returns a handle to the internal buffer
*/
virtual const char* GetInternalBuffer() const = 0;
- /** Required for the GetFilteredCopy implementation
+ /** Required for the GetFilteredCopy() implementation
* \returns the size of the internal buffer
*/
virtual pdf_long GetInternalBufferSize() const = 0;
@@ -277,10 +281,11 @@
/** Begin appending data to this stream.
* Clears the current stream contents.
*
- * Use PdfFilterFactory::CreateFilterList if you want to use the contents
+ * Use PdfFilterFactory::CreateFilterList() if you want to use the contents
* of the stream dictionary's existing filter key.
*
- * \param vecFilters use this filters to encode any data written to the stream.
+ * \param vecFilters use these filters to encode any data written
+ * to the stream.
*/
virtual void BeginAppendImpl( const TVecFilters & vecFilters ) = 0;
Index: src/base/PdfFilter.h
===================================================================
--- src/base/PdfFilter.h (revision 1676)
+++ src/base/PdfFilter.h (working copy)
@@ -71,14 +71,14 @@
*/
inline virtual ~PdfFilter();
- /** Check wether encoding is implemented for this filter.
+ /** Check whether encoding is implemented for this filter.
*
* \returns true if the filter is able to encode data
*/
virtual bool CanEncode() const = 0;
- /** Encodes a buffer using a filter. The buffer will malloc'ed and
- * has to be free'd by the caller.
+ /** Encodes a buffer using a filter. The buffer will malloc()'d and
+ * has to be free()'d by the caller.
*
* This function uses BeginEncode()/EncodeBlock()/EndEncode()
* internally, so it's not safe to use when progressive encoding
@@ -86,8 +86,8 @@
*
* \param pInBuffer input buffer
* \param lInLen length of the input buffer
- * \param ppOutBuffer pointer to the buffer of the encoded data
- * \param plOutLen pointer to the length of the output buffer
+ * \param ppOutBuffer receives pointer to the buffer of the encoded data
+ * \param plOutLen pointer to where to write the output buffer's length
*/
void Encode( const char* pInBuffer, pdf_long lInLen, char** ppOutBuffer, pdf_long* plOutLen ) const;
@@ -99,7 +99,7 @@
*
* \param pOutput encoded data will be written to this stream.
*
- * Call EncodeBlock() to encode blocks of data and use EndEncode
+ * Call EncodeBlock() to encode blocks of data and use EndEncode()
* to finish the encoding process.
*
* \see EncodeBlock
@@ -108,7 +108,7 @@
inline void BeginEncode( PdfOutputStream* pOutput );
/** Encode a block of data and write it to the PdfOutputStream
- * specified by BeginEncode. Ownership of the block is not taken
+ * specified by BeginEncode(). Ownership of the block is not taken
* and remains with the caller.
*
* The filter implementation need not immediately process the buffer,
@@ -123,7 +123,7 @@
* \param pBuffer pointer to a buffer with data to encode
* \param lLen length of data to encode.
*
- * Call EndEncode() after all data has been encoded
+ * Call EndEncode() after all data has been encoded.
*
* \see BeginEncode
* \see EndEncode
@@ -138,23 +138,23 @@
*/
inline void EndEncode();
- /** Check wether the decoding is implemented for this filter.
+ /** Check whether the decoding is implemented for this filter.
*
* \returns true if the filter is able to decode data
*/
virtual bool CanDecode() const = 0;
- /** Decodes a buffer using a filter. The buffer will malloc'ed and
- * has to be free'd by the caller.
+ /** Decodes a buffer using a filter. The buffer will malloc()'d and
+ * has to be free()'d by the caller.
*
* \param pInBuffer input buffer
* \param lInLen length of the input buffer
- * \param ppOutBuffer pointer to the buffer of the decoded data
- * \param plOutLen pointer to the length of the output buffer
- * \param pDecodeParms optional pointer to an decode parameters dictionary
- * containing additional information to decode the data.
- * This pointer must be NULL if no decode parameter dictionary
- * is available.
+ * \param ppOutBuffer receives pointer to the buffer of the decoded data
+ * \param plOutLen pointer to where to write the output buffer's length
+ * \param pDecodeParms optional pointer to an decode-parameters dictionary
+ * containing additional information to decode
+ * the data. This pointer must be NULL if no
+ * decode-parameters dictionary is available.
*/
void Decode( const char* pInBuffer, pdf_long lInLen, char** ppOutBuffer, pdf_long* plOutLen, const PdfDictionary* pDecodeParms = NULL ) const;
@@ -164,10 +164,11 @@
* perform other operations defined by particular filter
* implementations. It calls BeginDecodeImpl().
*
- * \param pOutput decoded data will be written to this stream.
- * \param pDecodeParms a dictionary containing addiational information for decoding
+ * \param pOutput decoded data will be written to this stream
+ * \param pDecodeParms a dictionary containing addiational information
+ * for decoding
*
- * Call DecodeBlock() to decode blocks of data and use EndDecode
+ * Call DecodeBlock() to decode blocks of data and use EndDecode()
* to finish the decoding process.
*
* \see DecodeBlock
@@ -176,7 +177,7 @@
inline void BeginDecode( PdfOutputStream* pOutput, const PdfDictionary* pDecodeParms = NULL );
/** Decode a block of data and write it to the PdfOutputStream
- * specified by BeginDecode. Ownership of the block is not taken
+ * specified by BeginDecode(). Ownership of the block is not taken
* and remains with the caller.
*
* The filter implementation need not immediately process the buffer,
@@ -191,7 +192,7 @@
* \param pBuffer pointer to a buffer with data to encode
* \param lLen length of data to encode.
*
- * Call EndDecode() after all data has been decoded
+ * Call EndDecode() after all data has been decoded.
*
* \see BeginDecode
* \see EndDecode
@@ -215,30 +216,33 @@
protected:
/**
- * Indicate that the filter has failed, and will be non-functional until BeginEncode()
- * or BeginDecode() is next called. Call this instead of EndEncode() or EndDecode if
- * something went wrong. It clears the stream output but otherwise does nothing.
+ * Indicate that the filter has failed, and will be non-functional
+ * until BeginEncode() or BeginDecode() is next called. Call this
+ * instead of EndEncode() or EndDecode if something went wrong.
+ * It clears the stream output but otherwise does nothing.
*
- * After this method is called futher calls to EncodeBlock(), DecodeBlock(), EndDecode() and
- * EndEncode() before the next BeginEncode() or BeginDecode() are guaranteed to throw
+ * After this method is called further calls to EncodeBlock(),
+ * DecodeBlock(), EndDecode() and EndEncode() before the next
+ * BeginEncode() or BeginDecode() are guaranteed to throw
* without calling their virtual implementations.
*/
PODOFO_NOTHROW inline void FailEncodeDecode();
- /** Real implementation of `BeginEncode()'. NEVER call this method directly.
+ /** Real implementation of BeginEncode(). NEVER call this method directly.
*
- * By default this function does nothing. If your filter needs to do setup for encoding,
- * you should override this method.
+ * By default this function does nothing. If your filter needs to do setup
+ * for encoding, you should override this method.
*
- * PdfFilter ensures that a valid stream is available when this method is called, and
- * that EndEncode() was called since the last BeginEncode()/EncodeBlock().
- *
- * \see BeginEncode */
+ * PdfFilter ensures that a valid stream is available when this method is
+ * called, and that EndEncode() was called since the last BeginEncode()/
+ * EncodeBlock().
+ * \see BeginEncode
+ */
virtual void BeginEncodeImpl( ) { }
- /** Real implementation of `EncodeBlock()'. NEVER call this method directly.
+ /** Real implementation of EncodeBlock(). NEVER call this method directly.
*
- * You must override this method to encode the buffer passed by the caller.
+ * You must method-override it to encode the buffer passed by the caller.
*
* You are not obliged to immediately process any or all of the data in
* the passed buffer, but you must ensure that you have processed it and
@@ -250,34 +254,36 @@
* called, ensures that BeginEncode() has been called, and ensures that
* EndEncode() has not been called since the last BeginEncode().
*
- * \see EncodeBlock */
+ * \see EncodeBlock
+ */
virtual void EncodeBlockImpl( const char* pBuffer, pdf_long lLen ) = 0;
- /** Real implementation of `EndEncode()'. NEVER call this method directly.
+ /** Real implementation of EndEncode(). NEVER call this method directly.
*
- * By the time this method returns, all filtered data must be written to the stream
- * and the filter must be in a state where BeginEncode() can be safely called.
+ * By the time this method returns, all filtered data must be written to
+ * the stream and the filter must be in a state where BeginEncode() can
+ * be safely called.
+ * PdfFilter ensures that a valid stream is available when this method is
+ * called, and ensures that BeginEncodeImpl() has been called.
*
- * PdfFilter ensures that a valid stream is available when this method is
- * called, and ensures that BeginEncodeImpl() has been called.
- *
- * \see EndEncode */
+ * \see EndEncode
+ */
virtual void EndEncodeImpl() { }
- /** Real implementation of `BeginDecode()'. NEVER call this method directly.
+ /** Real implementation of BeginDecode(). NEVER call this method directly.
*
- * By default this function does nothing. If your filter needs to do setup for decoding,
- * you should override this method.
+ * By default this function does nothing. If your filter needs to do setup
+ * for decoding, you should override this method.
*
- * PdfFilter ensures that a valid stream is available when this method is called, and
- * that EndDecode() was called since the last BeginDecode()/DecodeBlock().
- *
+ * PdfFilter ensures that a valid stream is available when this method is
+ * called, and that EndDecode() was called since the last BeginDecode()/
+ * DecodeBlock().
* \see BeginDecode */
virtual void BeginDecodeImpl( const PdfDictionary* ) { }
- /** Real implementation of `DecodeBlock()'. NEVER call this method directly.
+ /** Real implementation of DecodeBlock(). NEVER call this method directly.
*
- * You must override this method to decode the buffer passed by the caller.
+ * You must method-override it to decode the buffer passed by the caller.
*
* You are not obliged to immediately process any or all of the data in
* the passed buffer, but you must ensure that you have processed it and
@@ -289,18 +295,20 @@
* called, ensures that BeginDecode() has been called, and ensures that
* EndDecode() has not been called since the last BeginDecode().
*
- * \see DecodeBlock */
+ * \see DecodeBlock
+ */
virtual void DecodeBlockImpl( const char* pBuffer, pdf_long lLen ) = 0;
/** Real implementation of `EndDecode()'. NEVER call this method directly.
*
- * By the time this method returns, all filtered data must be written to the stream
- * and the filter must be in a state where BeginDecode() can be safely called.
- *
+ * By the time this method returns, all filtered data must be written to
+ * the stream and the filter must be in a state where BeginDecode() can be
+ * safely called.
* PdfFilter ensures that a valid stream is available when this method is
* called, and ensures that BeginDecodeImpl() has been called.
*
- * \see EndDecode */
+ * \see EndDecode
+ */
virtual void EndDecodeImpl() { }
private:
@@ -437,8 +445,8 @@
}
-/** A factory to create a filter object for a filter GetType from the EPdfFilter enum.
- *
+/** A factory to create a filter object for a filter type (as GetType() gives)
+ * from the EPdfFilter enum.
* All filters should be created using this factory.
*/
class PODOFO_API PdfFilterFactory {
@@ -445,9 +453,9 @@
public:
/** Create a filter from an enum.
*
- * Ownership is transferred to the caller, who should let the auto_ptr the
- * filter is returned in take care of freeing it when they're done with
- * it.
+ * Ownership is transferred to the caller, who should let the auto_ptr
+ * the filter is returned in take care of freeing it when they're done
+ * with it.
*
* \param eFilter the GetType of filter that should be created.
*
@@ -460,7 +468,8 @@
* on all data written to it.
*
* \param filters a list of filters
- * \param pStream write all data to this PdfOutputStream after it has been encoded.
+ * \param pStream write all data to this PdfOutputStream after it has been
+ * encoded.
* \returns a new PdfOutputStream that has to be deleted by the caller.
*
* \see PdfFilterFactory::CreateFilterList
@@ -471,12 +480,13 @@
* on all data written to it.
*
* \param filters a list of filters
- * \param pStream write all data to this PdfOutputStream after it has been decoded.
- * \param pDictionary pointer to a dictionary that might contain additional parameters
- * for decoding the stream.
- * CreateDecodeStream will look for a key named DecodeParms in this dictionary
- * and pass the information found in this dictionary to the filters.
- *
+ * \param pStream write all data to this PdfOutputStream
+ * after it has been decoded.
+ * \param pDictionary pointer to a dictionary that might
+ * contain additional parameters for stream decoding.
+ * This method will look for a key named DecodeParms
+ * in this dictionary and pass the information found in
+ * that dictionary (if found, else the argument) to the filters.
* \returns a new PdfOutputStream that has to be deleted by the caller.
*
* \see PdfFilterFactory::CreateFilterList
------------------------------------------------------------------------------
_______________________________________________
Podofo-users mailing list
Podofo-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/podofo-users
