Continue documentation cleanup
Reformat some more public/ header documentation.
Review URL: https://codereview.chromium.org/1917103002
diff --git a/public/fpdf_dataavail.h b/public/fpdf_dataavail.h
index effa68e..5599171 100644
--- a/public/fpdf_dataavail.h
+++ b/public/fpdf_dataavail.h
@@ -64,7 +64,7 @@
// Destroy the |avail| document availability provider.
//
-// |avail| - handle to document availability provider to be destroyed.
+// avail - handle to document availability provider to be destroyed.
DLLEXPORT void STDCALL FPDFAvail_Destroy(FPDF_AVAIL avail);
// Download hints interface. Used to receive hints for further downloading.
diff --git a/public/fpdf_ext.h b/public/fpdf_ext.h
index c80dcbb..d00c568 100644
--- a/public/fpdf_ext.h
+++ b/public/fpdf_ext.h
@@ -11,98 +11,87 @@
#ifdef __cplusplus
extern "C" {
-#endif
+#endif // __cplusplus
-// flags for type of unsupport object.
+// Unsupported XFA form.
#define FPDF_UNSP_DOC_XFAFORM 1
+// Unsupported portable collection.
#define FPDF_UNSP_DOC_PORTABLECOLLECTION 2
+// Unsupported attachment.
#define FPDF_UNSP_DOC_ATTACHMENT 3
+// Unsupported security.
#define FPDF_UNSP_DOC_SECURITY 4
+// Unsupported shared review.
#define FPDF_UNSP_DOC_SHAREDREVIEW 5
+// Unsupported shared form, acrobat.
#define FPDF_UNSP_DOC_SHAREDFORM_ACROBAT 6
+// Unsupported shared form, filesystem.
#define FPDF_UNSP_DOC_SHAREDFORM_FILESYSTEM 7
+// Unsupported shared form, email.
#define FPDF_UNSP_DOC_SHAREDFORM_EMAIL 8
+// Unsupported 3D annotation.
#define FPDF_UNSP_ANNOT_3DANNOT 11
+// Unsupported movie annotation.
#define FPDF_UNSP_ANNOT_MOVIE 12
+// Unsupported sound annotation.
#define FPDF_UNSP_ANNOT_SOUND 13
+// Unsupported screen media annotation.
#define FPDF_UNSP_ANNOT_SCREEN_MEDIA 14
+// Unsupported screen rich media annotation.
#define FPDF_UNSP_ANNOT_SCREEN_RICHMEDIA 15
+// Unsupported attachment annotation.
#define FPDF_UNSP_ANNOT_ATTACHMENT 16
+// Unsupported signature annotation.
#define FPDF_UNSP_ANNOT_SIG 17
+// Interface for unsupported feature notifications.
typedef struct _UNSUPPORT_INFO {
- /**
- * Version number of the interface. Currently must be 1.
- **/
+ // Version number of the interface. Must be 1.
int version;
- /**
- * Method: FSDK_UnSupport_Handler
- * UnSupport Object process handling function.
- * Interface Version:
- * 1
- * Implementation Required:
- * Yes
- * Parameters:
- * pThis - Pointer to the interface structure itself.
- * nType - The type of unsupportObject
- * Return value:
- * None.
- * */
-
+ // Unsupported object notification function.
+ // Interface Version: 1
+ // Implementation Required: Yes
+ //
+ // pThis - pointer to the interface structure.
+ // nType - the type of unsupported object. One of the |FPDF_UNSP_*| entries.
void (*FSDK_UnSupport_Handler)(struct _UNSUPPORT_INFO* pThis, int nType);
} UNSUPPORT_INFO;
-/**
- * Function: FSDK_SetUnSpObjProcessHandler
- * Setup A UnSupport Object process handler for foxit sdk.
- * Parameters:
- * unsp_info - Pointer to a UNSUPPORT_INFO structure.
- * Return Value:
- * TRUE means successful. FALSE means fails.
- **/
-
+// Setup an unsupported object handler.
+//
+// unsp_info - Pointer to an UNSUPPORT_INFO structure.
+//
+// Returns TRUE on success.
DLLEXPORT FPDF_BOOL STDCALL
FSDK_SetUnSpObjProcessHandler(UNSUPPORT_INFO* unsp_info);
-// flags for page mode.
-
-// Unknown value
+// Unknown page mode.
#define PAGEMODE_UNKNOWN -1
-
-// Neither document outline nor thumbnail images visible
+// Document outline, and thumbnails hidden.
#define PAGEMODE_USENONE 0
-
-// Document outline visible
+// Document outline visible.
#define PAGEMODE_USEOUTLINES 1
-
-// Thumbnial images visible
+// Thumbnail images visible.
#define PAGEMODE_USETHUMBS 2
-
-// Full-screen mode, with no menu bar, window controls, or any other window
-// visible
+// Full-screen mode, no menu bar, window controls, or other decorations visible.
#define PAGEMODE_FULLSCREEN 3
-
-// Optional content group panel visible
+// Optional content group panel visible.
#define PAGEMODE_USEOC 4
-
-// Attachments panel visible
+// Attachments panel visible.
#define PAGEMODE_USEATTACHMENTS 5
-/**
- * Function: FPDFDoc_GetPageMode
- * Get the document's PageMode(How the document should be displayed
- *when opened)
- * Parameters:
- * doc - Handle to document. Returned by FPDF_LoadDocument
- *function.
- * Return Value:
- * The flags for page mode.
- **/
+// Get the document's PageMode.
+//
+// doc - Handle to document.
+//
+// Returns one of the |PAGEMODE_*| flags defined above.
+//
+// The page mode defines how the document should be initially displayed.
DLLEXPORT int FPDFDoc_GetPageMode(FPDF_DOCUMENT document);
#ifdef __cplusplus
-}
-#endif
+} // extern "C"
+#endif // __cplusplus
#endif // PUBLIC_FPDF_EXT_H_
diff --git a/public/fpdf_flatten.h b/public/fpdf_flatten.h
index af77c29..8d64180 100644
--- a/public/fpdf_flatten.h
+++ b/public/fpdf_flatten.h
@@ -9,37 +9,35 @@
#include "fpdfview.h"
-// Result codes.
-#define FLATTEN_FAIL 0 // Flatten operation failed.
-#define FLATTEN_SUCCESS 1 // Flatten operation succeed.
-#define FLATTEN_NOTHINGTODO 2 // There is nothing to be flattened.
+// Flatten operation failed.
+#define FLATTEN_FAIL 0
+// Flatten operation succeed.
+#define FLATTEN_SUCCESS 1
+// Nothing to be flattened.
+#define FLATTEN_NOTHINGTODO 2
-// Flags.
+// Flatten for normal display.
#define FLAT_NORMALDISPLAY 0
+// Flatten for print.
#define FLAT_PRINT 1
#ifdef __cplusplus
extern "C" {
-#endif
+#endif // __cplusplus
-// Function: FPDFPage_Flatten
-// Make annotations and form fields become part of the page contents
-// itself.
-// Parameters:
-// page - Handle to the page, as returned by FPDF_LoadPage().
-// nFlag - Intended use of the flattened result: 0 for normal display,
-// 1 for printing.
-// Return value:
-// Either FLATTEN_FAIL, FLATTEN_SUCCESS, or FLATTEN_NOTHINGTODO (see
-// above).
-// Comments:
-// Currently, all failures return FLATTEN_FAIL, with no indication for
-// the reason
-// for the failure.
+// Flatten annotations and form fields into the page contents.
+//
+// page - handle to the page.
+// nFlag - One of the |FLAT_*| values denoting the page usage.
+//
+// Returns one of the |FLATTEN_*| values.
+//
+// Currently, all failures return |FLATTEN_FAIL| with no indication of the
+// cause.
DLLEXPORT int STDCALL FPDFPage_Flatten(FPDF_PAGE page, int nFlag);
#ifdef __cplusplus
-}
-#endif
+} // extern "C"
+#endif // __cplusplus
#endif // PUBLIC_FPDF_FLATTEN_H_
diff --git a/public/fpdf_fwlevent.h b/public/fpdf_fwlevent.h
index 22c01e4..511c6a3 100644
--- a/public/fpdf_fwlevent.h
+++ b/public/fpdf_fwlevent.h
@@ -11,19 +11,20 @@
#ifdef __cplusplus
extern "C" {
-#endif
+#endif // __cplusplus
typedef int FPDF_INT32;
typedef unsigned int FPDF_UINT32;
typedef float FPDF_FLOAT;
-// event type
+
+// Event types.
typedef enum {
FWL_EVENTTYPE_Mouse = 0,
FWL_EVENTTYPE_MouseWheel,
FWL_EVENTTYPE_Key,
} FWL_EVENTTYPE;
-// key flag
+// Key flags.
typedef enum {
FWL_EVENTFLAG_ShiftKey = 1 << 0,
FWL_EVENTFLAG_ControlKey = 1 << 1,
@@ -36,7 +37,7 @@
FWL_EVENTFLAG_RightButtonDown = 1 << 8,
} FWL_EVENTFLAG;
-// Mouse message command
+// Mouse messages.
typedef enum {
FWL_EVENTMOUSECMD_LButtonDown = 1,
FWL_EVENTMOUSECMD_LButtonUp,
@@ -53,7 +54,7 @@
FWL_EVENTMOUSECMD_MouseLeave,
} FWL_EVENT_MOUSECMD;
-// mouse event
+// Mouse events.
struct FWL_EVENT_MOUSE {
FPDF_UINT32 command;
FPDF_DWORD flag;
@@ -61,7 +62,7 @@
FPDF_FLOAT y;
};
-// mouse wheel
+// Mouse wheel events.
struct FWL_EVENT_MOUSEWHEEL {
FPDF_DWORD flag;
FPDF_FLOAT x;
@@ -70,7 +71,7 @@
FPDF_FLOAT deltaY;
};
-// virtual keycode
+// Virtual keycodes.
typedef enum {
FWL_VKEY_Back = 0x08,
FWL_VKEY_Tab = 0x09,
@@ -242,14 +243,14 @@
FWL_VKEY_Unknown = 0,
} FWL_VKEYCODE;
-// key event command
+// Key event commands.
typedef enum {
FWL_EVENTKEYCMD_KeyDown = 1,
FWL_EVENTKEYCMD_KeyUp,
FWL_EVENTKEYCMD_Char,
} FWL_EVENTKEYCMD;
-// key event
+// Key events.
struct FWL_EVENT_KEY {
FPDF_UINT32 command;
FPDF_DWORD flag;
@@ -261,9 +262,9 @@
} code;
};
-// event type
+// Event types.
struct FWL_EVENT {
- // structure size.
+ // Structure size.
FPDF_UINT32 size;
// FWL_EVENTTYPE.
FPDF_UINT32 type;
@@ -275,7 +276,7 @@
};
#ifdef __cplusplus
-}
-#endif
+} // extern "C"
+#endif // __cplusplus
#endif // PUBLIC_FPDF_FWLEVENT_H_
diff --git a/public/fpdf_ppo.h b/public/fpdf_ppo.h
index e7d7767..532494e 100644
--- a/public/fpdf_ppo.h
+++ b/public/fpdf_ppo.h
@@ -13,35 +13,31 @@
extern "C" {
#endif
-// Function: FPDF_ImportPages
-// Import some pages to a PDF document.
-// Parameters:
-// dest_doc - The destination document which add the pages.
-// src_doc - A document to be imported.
-// pagerange - A page range string, Such as "1,3,5-7".
-// If this parameter is NULL, it would import all pages
-// in src_doc.
-// index - The page index wanted to insert from.
-// Return value:
-// TRUE for succeed, FALSE for Failed.
+// Import pages to a FPDF_DOCUMENT.
+//
+// dest_doc - The destination document for the pages.
+// src_doc - The document to be imported.
+// pagerange - A page range string, Such as "1,3,5-7". If |pagerange| is NULL,
+// all pages from |src_doc| are imported.
+// index - The page index to insert at.
+//
+// Returns TRUE on success.
DLLEXPORT FPDF_BOOL STDCALL FPDF_ImportPages(FPDF_DOCUMENT dest_doc,
FPDF_DOCUMENT src_doc,
FPDF_BYTESTRING pagerange,
int index);
-// Function: FPDF_CopyViewerPreferences
-// Copy the viewer preferences from one PDF document to another.#endif
-// Parameters:
-// dest_doc - Handle to document to write the viewer preferences
-// to.
-// src_doc - Handle to document with the viewer preferences.
-// Return value:
-// TRUE for success, FALSE for failure.
+// Copy the viewer preferences from |src_doc| into |dest_doc|.
+//
+// dest_doc - Document to write the viewer preferences into.
+// src_doc - Document to read the viewer preferences from.
+//
+// Returns TRUE on success.
DLLEXPORT FPDF_BOOL STDCALL FPDF_CopyViewerPreferences(FPDF_DOCUMENT dest_doc,
FPDF_DOCUMENT src_doc);
#ifdef __cplusplus
-}
-#endif
+} // extern "C"
+#endif // __cplusplus
#endif // PUBLIC_FPDF_PPO_H_
diff --git a/public/fpdf_searchex.h b/public/fpdf_searchex.h
index a6b6e1b..0d90bdd 100644
--- a/public/fpdf_searchex.h
+++ b/public/fpdf_searchex.h
@@ -11,22 +11,19 @@
#ifdef __cplusplus
extern "C" {
-#endif
+#endif // __cplusplus
-// Function: FPDFText_GetCharIndexFromTextIndex
-// Get the actually char index in text_page's internal char list.
-// Parameters:
-// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
-// nTextIndex - The index of the text in the string get from
-// FPDFText_GetText.
-// Return value:
-// The index of the character in internal charlist. -1 for error.
+// Get the character index in |text_page| internal character list.
+//
+// text_page - a text page information structure.
+// nTextIndex - index of the text returned from |FPDFText_GetText|.
+//
+// Returns the index of the character in internal character list. -1 for error.
DLLEXPORT int STDCALL
FPDFText_GetCharIndexFromTextIndex(FPDF_TEXTPAGE text_page, int nTextIndex);
#ifdef __cplusplus
-}
-#endif
+} // extern "C"
+#endif // __cplusplus
#endif // PUBLIC_FPDF_SEARCHEX_H_