Hi all,
I contribute the attached patch cleaning up documentation for methods
with return type "void" and a constructor where a return of "ErrOk" is
still mentioned: it removes such mentions, also clarifies some parameter
and method documentation and corrects the constructor's documentation.
Removal of @returns in favor of \returns and correction of return-value
documentation (both in PdfVariant.h) are also contained in the patch.
Please review this patch and if accepted, plase apply it separately to a
working copy unmodified relative to the (public) repository branch you'll
commit it to. Please use this mail's first paragraph for the long form
(after the first line) of the commit message (substituting "I contribute"
as appropriate) because the patch contains only the short form.
Best regards, mabri
documentation cleanup for "ErrOk on success" return value where none is given
Index: src/base/PdfDictionary.h
===================================================================
--- src/base/PdfDictionary.h (revision 1676)
+++ src/base/PdfDictionary.h (working copy)
@@ -208,8 +208,7 @@
*/
bool RemoveKey( const PdfName & identifier );
- /** Write the complete dictionary to a file. \param pDevice write the
- * object to this device \returns ErrOk on success
+ /** Write the complete dictionary to a file.
*
* \param pDevice write the object to this device
* \param eWriteMode additional options for writing this object
@@ -218,10 +217,7 @@
*/
inline void Write( PdfOutputDevice* pDevice, EPdfWriteMode eWriteMode, const PdfEncrypt* pEncrypt = NULL ) const;
- /** Write the complete dictionary to a file. \param pDevice write the
- * object to this device \param keyStop if not KeyNull and a key == keyStop
- * is found writing will stop right before this key! \returns ErrOk on
- * success
+ /** Write the complete dictionary to a file.
*
* \param pDevice write the object to this device
* \param eWriteMode additional options for writing this object
Index: src/base/PdfFileStream.h
===================================================================
--- src/base/PdfFileStream.h (revision 1676)
+++ src/base/PdfFileStream.h (working copy)
@@ -95,9 +95,8 @@
* This is currently not implemented for PdfFileStreams
* and will raise an ePdfError_InternalLogic exception
*
- * \param pBuffer pointer to the buffer
- * \param lLen pointer to the buffer length
- * \returns ErrOk on success.
+ * \param pBuffer pointer to the buffer address (output parameter)
+ * \param lLen pointer to the buffer length (output parameter)
*/
virtual void GetCopy( char** pBuffer, pdf_long* lLen ) const;
Index: src/base/PdfMemStream.h
===================================================================
--- src/base/PdfMemStream.h (revision 1676)
+++ src/base/PdfMemStream.h (working copy)
@@ -89,9 +89,8 @@
*
* The caller has to free() the buffer.
*
- * \param pBuffer pointer to the buffer
- * \param lLen pointer to the buffer length
- * \returns ErrOk on success.
+ * \param pBuffer pointer to where the buffer's address will be stored
+ * \param lLen pointer to the buffer length (output parameter)
*/
virtual void GetCopy( char** pBuffer, pdf_long* lLen ) const;
@@ -178,9 +177,8 @@
virtual void EndAppendImpl();
private:
- /** Compress the current data using the FlateDecode(ZIP) algorithm
+ /** Compress the current data using the FlateDecode (zlib) algorithm
* Expects that all filters are setup correctly.
- * \returns ErrOk on success
*/
void FlateCompressStreamData();
Index: src/base/PdfOutputDevice.h
===================================================================
--- src/base/PdfOutputDevice.h (revision 1676)
+++ src/base/PdfOutputDevice.h (working copy)
@@ -125,7 +125,6 @@
* as the output might depend on the current locale.
*
* \param pszFormat a format string as you would use it with printf
- * \returns ErrOk on success
*
* \see Write
*/
@@ -139,7 +138,6 @@
* \param pszFormat a format string as you would use it with printf
* \param lBytes length of the format string in bytes when written
* \param argptr variable argument list
- * \returns ErrOk on success
*
* \see Write
*/
@@ -162,7 +160,6 @@
*
* \param pBuffer a pointer to the data buffer
* \param lLen write lLen bytes of pBuffer to the PdfOutputDevice
- * \returns ErrOk on success
*
* \see Print
*/
Index: src/base/PdfVariant.h
===================================================================
--- src/base/PdfVariant.h (revision 1676)
+++ src/base/PdfVariant.h (working copy)
@@ -113,14 +113,12 @@
*/
PdfVariant( const PdfReference & rRef );
- /** Initalize a PdfVariant object with array data.
+ /** Construct a PdfVariant object with array data.
* The variant will automatically get the datatype
- * ePdfDataType_Array. This Init call is the fastest
+ * ePdfDataType_Array. This constructor is the fastest
* way to create a new PdfVariant that is an array.
*
* \param tList a list of variants
- *
- * \returns ErrOk on sucess
*/
PdfVariant( const PdfArray & tList );
@@ -372,7 +370,7 @@
* This is used by PdfImmediateWriter and PdfStreamedDocument so
* that no keys can be added to an object after setting stream data on it.
*
- * @returns true if the object is immutable
+ * \returns true if the object is immutable
*/
inline bool GetImmutable() const;
@@ -454,12 +452,12 @@
inline PdfDictionary & GetDictionary_NoDL();
/** Version of GetArray() that doesn't trigger a delayed load
- * \returns a array
+ * \returns a PdfArray
*/
inline const PdfArray & GetArray_NoDL() const;
/** Version of GetArray() that doesn't trigger a delayed load.
- * \returns a array
+ * \returns a PdfArray
*/
inline PdfArray & GetArray_NoDL();
Index: src/base/PdfWriter.h
===================================================================
--- src/base/PdfWriter.h (revision 1676)
+++ src/base/PdfWriter.h (working copy)
@@ -177,11 +177,11 @@
*
* Better use a PdfOutputDevice that writes to a PdfRefCountedBuffer.
*
- * \param ppBuffer will be malloc'ed and the document
- * will be written to this buffer.
- * \param pulLen the length of the buffer will be returned in this parameter
- * \returns ErrOk on success
- *
+ * \param ppBuffer where this points the address of the buffer will
+ * be written after that being malloc()'d and the document
+ * will be written to that buffer.
+ * \param pulLen the buffer length will be returned in this parameter
+ *
* \see Write
*/
void WriteToBuffer( char** ppBuffer, pdf_long* pulLen );
------------------------------------------------------------------------------
_______________________________________________
Podofo-users mailing list
Podofo-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/podofo-users
