From 860193b775f19a176963e31d41f641455499fccb Mon Sep 17 00:00:00 2001 From: dsinclair Date: Mon, 25 Apr 2016 19:44:20 -0700 Subject: Continue documentation cleanup Reformat some more public/ header documentation. Review URL: https://codereview.chromium.org/1917103002 --- public/fpdf_dataavail.h | 2 +- public/fpdf_ext.h | 101 +++++++++++++++++++++--------------------------- public/fpdf_flatten.h | 46 +++++++++++----------- public/fpdf_fwlevent.h | 27 ++++++------- public/fpdf_ppo.h | 38 ++++++++---------- public/fpdf_searchex.h | 21 +++++----- 6 files changed, 108 insertions(+), 127 deletions(-) diff --git a/public/fpdf_dataavail.h b/public/fpdf_dataavail.h index effa68e179..5599171619 100644 --- a/public/fpdf_dataavail.h +++ b/public/fpdf_dataavail.h @@ -64,7 +64,7 @@ DLLEXPORT FPDF_AVAIL STDCALL FPDFAvail_Create(FX_FILEAVAIL* file_avail, // 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 c80dcbbf58..d00c568241 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 af77c29343..8d641809fe 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. - -// Flags. +// Flatten operation failed. +#define FLATTEN_FAIL 0 +// Flatten operation succeed. +#define FLATTEN_SUCCESS 1 +// Nothing to be flattened. +#define FLATTEN_NOTHINGTODO 2 + +// Flatten for normal display. #define FLAT_NORMALDISPLAY 0 +// Flatten for print. #define FLAT_PRINT 1 #ifdef __cplusplus extern "C" { -#endif - -// 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. +#endif // __cplusplus + +// 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 22c01e4297..511c6a3480 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 @@ typedef enum { 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 @@ typedef enum { FWL_EVENTMOUSECMD_MouseLeave, } FWL_EVENT_MOUSECMD; -// mouse event +// Mouse events. struct FWL_EVENT_MOUSE { FPDF_UINT32 command; FPDF_DWORD flag; @@ -61,7 +62,7 @@ struct FWL_EVENT_MOUSE { FPDF_FLOAT y; }; -// mouse wheel +// Mouse wheel events. struct FWL_EVENT_MOUSEWHEEL { FPDF_DWORD flag; FPDF_FLOAT x; @@ -70,7 +71,7 @@ struct FWL_EVENT_MOUSEWHEEL { FPDF_FLOAT deltaY; }; -// virtual keycode +// Virtual keycodes. typedef enum { FWL_VKEY_Back = 0x08, FWL_VKEY_Tab = 0x09, @@ -242,14 +243,14 @@ typedef enum { 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 @@ struct FWL_EVENT_KEY { } code; }; -// event type +// Event types. struct FWL_EVENT { - // structure size. + // Structure size. FPDF_UINT32 size; // FWL_EVENTTYPE. FPDF_UINT32 type; @@ -275,7 +276,7 @@ struct FWL_EVENT { }; #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 e7d77678f9..532494e7fa 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 a6b6e1bdbf..0d90bdddb9 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_ -- cgit v1.2.3