Continue documentation cleanup

Reformat some more public/ header documentation.

Review URL: https://codereview.chromium.org/1917103002

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_