Add smaller less-scary comment about FPDF_DestroyLibrary().
-- Move deprecated initialization function below supported one so
that readers will see the supported one first.
-- Tweak some language, avoid saying FPDFSDK.
Change-Id: I8317fb026855bd8da2c5101b54ef0c6d2938ca68
Reviewed-on: https://pdfium-review.googlesource.com/c/pdfium/+/108110
Auto-Submit: Tom Sepez <tsepez@chromium.org>
Commit-Queue: Lei Zhang <thestig@chromium.org>
Reviewed-by: Lei Zhang <thestig@chromium.org>
diff --git a/public/fpdfview.h b/public/fpdfview.h
index 77196dc..1527090 100644
--- a/public/fpdfview.h
+++ b/public/fpdfview.h
@@ -106,12 +106,14 @@
// String types
typedef unsigned short FPDF_WCHAR;
-// FPDFSDK may use three types of strings: byte string, wide string (UTF-16LE
-// encoded), and platform dependent string
+// The public PDFium API uses three types of strings: byte string, wide string
+// (UTF-16LE encoded), and platform dependent string.
+
+// Public PDFium API type for byte strings.
typedef const char* FPDF_BYTESTRING;
-// FPDFSDK always uses UTF-16LE encoded wide strings, each character uses 2
-// bytes (except surrogation), with the low byte first.
+// The public PDFium API always uses UTF-16LE encoded wide strings, each
+// character uses 2 bytes (except surrogation), with the low byte first.
typedef const FPDF_WCHAR* FPDF_WIDESTRING;
// Structure for persisting a string beyond the duration of a callback.
@@ -230,18 +232,6 @@
extern "C" {
#endif
-// Function: FPDF_InitLibrary
-// Initialize the FPDFSDK library
-// Parameters:
-// None
-// Return value:
-// None.
-// Comments:
-// Convenience function to call FPDF_InitLibraryWithConfig() for
-// backwards compatibility purposes. This will be deprecated in the
-// future.
-FPDF_EXPORT void FPDF_CALLCONV FPDF_InitLibrary();
-
// PDF renderer types - Experimental.
// Selection of 2D graphics library to use for rendering to FPDF_BITMAPs.
typedef enum {
@@ -292,7 +282,7 @@
} FPDF_LIBRARY_CONFIG;
// Function: FPDF_InitLibraryWithConfig
-// Initialize the FPDFSDK library
+// Initialize the PDFium library and allocate global resources for it.
// Parameters:
// config - configuration information as above.
// Return value:
@@ -303,17 +293,33 @@
FPDF_EXPORT void FPDF_CALLCONV
FPDF_InitLibraryWithConfig(const FPDF_LIBRARY_CONFIG* config);
-// Function: FPDF_DestroyLibary
-// Release all resources allocated by the FPDFSDK library.
+// Function: FPDF_InitLibrary
+// Initialize the PDFium library (alternative form).
+// Parameters:
+// None
+// Return value:
+// None.
+// Comments:
+// Convenience function to call FPDF_InitLibraryWithConfig() with a
+// default configuration for backwards compatibility purposes. New
+// code should call FPDF_InitLibraryWithConfig() instead. This will
+// be deprecated in the future.
+FPDF_EXPORT void FPDF_CALLCONV FPDF_InitLibrary();
+
+// Function: FPDF_DestroyLibrary
+// Release global resources allocated to the PDFium library by
+// FPDF_InitLibrary() or FPDF_InitLibraryWithConfig().
// Parameters:
// None.
// Return value:
// None.
// Comments:
-// You can call this function to release all memory blocks allocated by
-// the library.
-// After this function is called, you should not call any PDF
+// After this function is called, you must not call any PDF
// processing functions.
+//
+// Calling this function does not automatically close other
+// objects. It is recommended to close other objects before
+// closing the library with this function.
FPDF_EXPORT void FPDF_CALLCONV FPDF_DestroyLibrary();
// Policy for accessing the local machine time.
@@ -443,7 +449,7 @@
// Position is specified by byte offset from the beginning of the file.
// The pointer to the buffer is never NULL and the size is never 0.
// The position and size will never go out of range of the file length.
- // It may be possible for FPDFSDK to call this function multiple times for
+ // It may be possible for PDFium to call this function multiple times for
// the same position.
// Return value: should be non-zero if successful, zero for error.
int (*m_GetBlock)(void* param,
