Cleanup fpdf_edit.h and fpdf_doc.h documentation.

This CL cleans up the documentation in public/fpdf_doc.h and public/fpdf_edit.h.

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

2 files changed, 325 insertions, 470 deletions

diff --git a/public/fpdf_doc.h b/public/fpdf_doc.h
index eae7c95e49..0b78743259 100644
--- a/public/fpdf_doc.h
+++ b/public/fpdf_doc.h
@@ -9,357 +9,277 @@
 
 #include "fpdfview.h"
 
-// Exported Functions
 #ifdef __cplusplus
 extern "C" {
-#endif
+#endif  // __cplusplus
 
-// Function: FPDFBookmark_GetFirstChild
-//          Get the first child of a bookmark item, or the first top level
-//          bookmark item.
-// Parameters:
-//          document    -   Handle to the document. Returned by
-//          FPDF_LoadDocument or FPDF_LoadMemDocument.
-//          bookmark    -   Handle to the current bookmark. Can be NULL if you
-//          want to get the first top level item.
-// Return value:
-//          Handle to the first child or top level bookmark item. NULL if no
-//          child or top level bookmark found.
+// Unsupported action type.
+#define PDFACTION_UNSUPPORTED 0
+// Go to a destination within current document.
+#define PDFACTION_GOTO 1
+// Go to a destination within another document.
+#define PDFACTION_REMOTEGOTO 2
+// URI, including web pages and other Internet resources.
+#define PDFACTION_URI 3
+// Launch an application or open a file.
+#define PDFACTION_LAUNCH 4
+
+typedef struct _FS_QUADPOINTSF {
+  FS_FLOAT x1;
+  FS_FLOAT y1;
+  FS_FLOAT x2;
+  FS_FLOAT y2;
+  FS_FLOAT x3;
+  FS_FLOAT y3;
+  FS_FLOAT x4;
+  FS_FLOAT y4;
+} FS_QUADPOINTSF;
+
+// Get the first child of |bookmark|, or the first top-level bookmark item.
+//
+//   document - handle to the document.
+//   bookmark - handle to the current bookmark. Pass NULL for the first top
+//              level item.
 //
+// Returns a handle to the first child of |bookmark| or the first top-level
+// bookmark item. NULL if no child or top-level bookmark found.
 DLLEXPORT FPDF_BOOKMARK STDCALL
 FPDFBookmark_GetFirstChild(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark);
 
-// Function: FPDFBookmark_GetNextSibling
-//          Get next bookmark item at the same level.
-// Parameters:
-//          document    -   Handle to the document. Returned by
-//          FPDF_LoadDocument or FPDF_LoadMemDocument.
-//          bookmark    -   Handle to the current bookmark. Cannot be NULL.
-// Return value:
-//          Handle to the next bookmark item at the same level. NULL if this is
-//          the last bookmark at this level.
+// Get the next sibling of |bookmark|.
 //
+//   document - handle to the document.
+//   bookmark - handle to the current bookmark.
+//
+// Returns a handle to the next sibling of |bookmark|, or NULL if this is the
+// last bookmark at this level.
 DLLEXPORT FPDF_BOOKMARK STDCALL
 FPDFBookmark_GetNextSibling(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark);
 
-// Function: FPDFBookmark_GetTitle
-//          Get title of a bookmark.
-// Parameters:
-//          bookmark    -   Handle to the bookmark.
-//          buffer      -   Buffer for the title. Can be NULL.
-//          buflen      -   The length of the buffer in bytes. Can be 0.
-// Return value:
-//          Number of bytes the title consumes, including trailing zeros.
-// Comments:
-//          Regardless of the platform, the title is always in UTF-16LE
-//          encoding. That means the buffer
-//          can be treated as an array of WORD (on Intel and compatible CPUs),
-//          each WORD representing the Unicode of
-//          a character(some special Unicode may take 2 WORDs).The string is
-//          followed by two bytes of zero
-//          indicating the end of the string.
-//
-//          The return value always indicates the number of bytes required for
-//          the buffer, even if no buffer is specified
-//          or the buffer size is less then required. In these cases, the buffer
-//          will not be modified.
+// Get the title of |bookmark|.
+//
+//   bookmark - handle to the bookmark.
+//   buffer   - buffer for the title. May be NULL.
+//   buflen   - the length of the buffer in bytes. May be 0.
 //
+// Returns the number of bytes in the title, including the terminating NUL
+// character. The number of bytes is returned regardless of the |buffer| and
+// |buflen| parameters.
+//
+// Regardless of the platform, the |buffer| is always in UTF-16LE encoding. The
+// string is terminated by a UTF16 NUL character. If |buflen| is less then the
+// required length, or |buffer| is NULL, |buffer| will not be modified.
 DLLEXPORT unsigned long STDCALL FPDFBookmark_GetTitle(FPDF_BOOKMARK bookmark,
                                                       void* buffer,
                                                       unsigned long buflen);
 
-// Function: FPDFBookmark_Find
-//          Find a bookmark in the document, using the bookmark title.
-// Parameters:
-//          document    -   Handle to the document. Returned by
-//          FPDF_LoadDocument or FPDF_LoadMemDocument.
-//          title       -   The UTF-16LE encoded Unicode string for the bookmark
-//          title to be searched. Can't be NULL.
-// Return value:
-//          Handle to the found bookmark item. NULL if the title can't be found.
-// Comments:
-//          It always returns the first found bookmark if more than one
-//          bookmarks have the same title.
+// Find the bookmark with |title| in |document|.
+//
+//   document - handle to the document.
+//   title    - the UTF-16LE encoded Unicode title for which to search.
 //
+// Returns the handle to the bookmark, or NULL if |title| can't be found.
+//
+// |FPDFBookmark_Find| will always return the first bookmark found even if
+// multiple bookmarks have the same |title|.
 DLLEXPORT FPDF_BOOKMARK STDCALL FPDFBookmark_Find(FPDF_DOCUMENT document,
                                                   FPDF_WIDESTRING title);
 
-// Function: FPDFBookmark_GetDest
-//          Get the destination associated with a bookmark item.
-// Parameters:
-//          document    -   Handle to the document.
-//          bookmark    -   Handle to the bookmark.
-// Return value:
-//          Handle to the destination data. NULL if no destination is associated
-//          with this bookmark.
+// Get the destination associated with |bookmark|.
+//
+//   document - handle to the document.
+//   bookmark - handle to the bookmark.
 //
+// Returns the handle to the destination data,  NULL if no destination is
+// associated with |bookmark|.
 DLLEXPORT FPDF_DEST STDCALL FPDFBookmark_GetDest(FPDF_DOCUMENT document,
                                                  FPDF_BOOKMARK bookmark);
 
-// Function: FPDFBookmark_GetAction
-//          Get the action associated with a bookmark item.
-// Parameters:
-//          bookmark    -   Handle to the bookmark.
-// Return value:
-//          Handle to the action data. NULL if no action is associated with this
-//          bookmark. In this case, the
-//          application should try FPDFBookmark_GetDest.
+// Get the action associated with |bookmark|.
+//
+//   bookmark - handle to the bookmark.
 //
+// Returns the handle to the action data, or NULL if no action is associated
+// with |bookmark|. When NULL is returned, |FPDFBookmark_GetDest| should be
+// called to get the |bookmark| destination data.
 DLLEXPORT FPDF_ACTION STDCALL FPDFBookmark_GetAction(FPDF_BOOKMARK bookmark);
 
-#define PDFACTION_UNSUPPORTED 0  // Unsupported action type.
-#define PDFACTION_GOTO 1         // Go to a destination within current document.
-#define PDFACTION_REMOTEGOTO 2   // Go to a destination within another document.
-#define PDFACTION_URI 3          // Universal Resource Identifier, including web
-                                 // pages and other Internet based resources.
-#define PDFACTION_LAUNCH 4       // Launch an application or open a file.
-
-// Function: FPDFAction_GetType
-//          Get type of an action.
-// Parameters:
-//          action      -   Handle to the action.
-// Return value:
-//          A type number as defined above.
+// Get the type of |action|.
+//
+//   action - handle to the action.
 //
+// Returns one of:
+//   PDFACTION_UNSUPPORTED
+//   PDFACTION_GOTO
+//   PDFACTION_REMOTEGOTO
+//   PDFACTION_URI
+//   PDFACTION_LAUNCH
 DLLEXPORT unsigned long STDCALL FPDFAction_GetType(FPDF_ACTION action);
 
-// Function: FPDFAction_GetDest
-//          Get destination of an action.
-// Parameters:
-//          document    -   Handle to the document.
-//          action      -   Handle to the action. It must be a GOTO or
-//          REMOTEGOTO action.
-// Return value:
-//          Handle to the destination data.
-// Comments:
-//          In case of remote goto action, the application should first use
-//          FPDFAction_GetFilePath to
-//          get file path, then load that particular document, and use its
-//          document handle to call this
-//          function.
+// Get the destination of |action|.
+//
+//   document - handle to the document.
+//   action   - handle to the action. |action| must be a |PDFACTION_GOTO| or
+//              |PDFACTION_REMOTEGOTO|.
 //
+// Returns a handle to the destination data.
+//
+// In the case of |PDFACTION_REMOTEGOTO|, you should first call
+// |FPDFAction_GetFilePath| then load that document, the document handle from
+// that document should pass as |document| to |FPDFAction_GetDest|.
 DLLEXPORT FPDF_DEST STDCALL FPDFAction_GetDest(FPDF_DOCUMENT document,
                                                FPDF_ACTION action);
 
-// Function: FPDFAction_GetFilePath
-//          Get file path of a remote goto action.
-// Parameters:
-//          action    -   Handle to the action. Must be a REMOTEGOTO or
-//                        LAUNCH action.
-//          buffer    -   A buffer for output the path string. Can be NULL.
-//          buflen    -   The length of the buffer, number of bytes. Can be 0.
-// Return value:
-//          Number of bytes the file path consumes, including trailing zero.
-//
-// Comments:
-//          The file path is UTF-8 encoded. The return value is the number of
-//          bytes required for the buffer, even when there is no buffer
-//          specified, or the buffer size is less then required. In this case,
-//          the buffer will not be modified.
+// Get file path of a |PDFACTION_REMOTEGOTO| |action|.
+//
+//   action - handle to the action. |action| must be a |PDFACTION_LAUNCH| or
+//            |PDFACTION_REMOTEGOTO|
+//   buffer - a buffer for output the path string. May be NULL.
+//   buflen - the length of the buffer, in bytes. May be 0.
+//
+// Returns the number of bytes in the file path, including the trailing UTF16
+// NUL character.
 //
+// Regardless of the platform, the |buffer| is always in UTF-16LE encoding.
+// If |buflen| is less then the returned length, or |buffer| is NULL, |buffer|
+// will not be modified.
 DLLEXPORT unsigned long STDCALL
 FPDFAction_GetFilePath(FPDF_ACTION action, void* buffer, unsigned long buflen);
 
-// Function: FPDFAction_GetURIPath
-//          Get URI path of a URI action.
-// Parameters:
-//          document    -   Handle to the document.
-//          action      -   Handle to the action. Must be a URI action.
-//          buffer      -   A buffer for output the path string. Can be NULL.
-//          buflen      -   The length of the buffer, number of bytes. Can be 0.
-// Return value:
-//          Number of bytes the URI path consumes, including trailing zeros.
-// Comments:
-//          The URI path is always encoded in 7-bit ASCII.
-//
-//          The return value is the number of bytes required for the buffer,
-//          even when there is no buffer specified, or the buffer size is less
-//          then required. In this case, the buffer will not be modified.
+// Get the URI path of a |PDFACTION_URI| |action|.
 //
+//   document - handle to the document.
+//   action   - handle to the action. Must be a |PDFACTION_URI|.
+//   buffer   - a buffer for the path string. May be NULL.
+//   buflen   - the length of the buffer, in bytes. May be 0.
+//
+// Returns the number of bytes in the URI path, including trailing zeros.
+//
+// The |buffer| is always encoded in 7-bit ASCII. If |buflen| is less then the
+// returned length, or |buffer| is NULL, |buffer| will not be modified.
 DLLEXPORT unsigned long STDCALL FPDFAction_GetURIPath(FPDF_DOCUMENT document,
                                                       FPDF_ACTION action,
                                                       void* buffer,
                                                       unsigned long buflen);
 
-// Function: FPDFDest_GetPageIndex
-//          Get page index of a destination.
-// Parameters:
-//          document    -   Handle to the document.
-//          dest        -   Handle to the destination.
-// Return value:
-//          The page index. Starting from 0 for the first page.
+// Get the page index of |dest|.
 //
+//   document - handle to the document.
+//   dest     - handle to the destination.
+//
+// Returns the page index containing |dest|. Page indices start from 0.
 DLLEXPORT unsigned long STDCALL FPDFDest_GetPageIndex(FPDF_DOCUMENT document,
                                                       FPDF_DEST dest);
 
-// Function: FPDFLink_GetLinkAtPoint
-//     Find a link at specified point on a document page.
-// Parameters:
-//     page        -   Handle to the document page.
-//     x           -   The x coordinate of the point, specified in page
-//                     coordinate system.
-//     y           -   The y coordinate of the point, specified in page
-//                     coordinate system.
-// Return value:
-//     Handle to the link. NULL if no link found at that point.
-// Comments:
-//     The point coordinates are specified in page coordinate system. You can
-//     convert coordinates from screen system to page system using
-//     FPDF_DeviceToPage().
+// Find a link at point (|x|,|y|) on |page|.
+//
+//   page - handle to the document page.
+//   x    - the x coordinate, in the page coordinate system.
+//   y    - the y coordinate, in the page coordinate system.
 //
+// Returns a handle to the link, or NULL if no link found at the given point.
+//
+// You can convert coordinates from screen coordinates to page coordinates using
+// |FPDF_DeviceToPage|.
 DLLEXPORT FPDF_LINK STDCALL FPDFLink_GetLinkAtPoint(FPDF_PAGE page,
                                                     double x,
                                                     double y);
 
-// Function: FPDFLink_GetLinkZOrderAtPoint
-//     Find the z-order of a link at specified point on a document page.
-// Parameters:
-//     page        -   Handle to the document page.
-//     x           -   The x coordinate of the point, specified in page
-//                     coordinate system.
-//     y           -   The y coordinate of the point, specified in page
-//                     coordinate system.
-// Return value:
-//     Z-order of the link, or -1 if no link found at that point.
-//     Higher numbers are closer to the front.
-// Comments:
-//     The point coordinates are specified in page coordinate system. You can
-//     convert coordinates from screen system to page system using
-//     FPDF_DeviceToPage().
+// Find the Z-order of link at point (|x|,|y|) on |page|.
+//
+//   page - handle to the document page.
+//   x    - the x coordinate, in the page coordinate system.
+//   y    - the y coordinate, in the page coordinate system.
+//
+// Returns the Z-order of the link, or -1 if no link found at the given point.
+// Larger Z-order numbers are closer to the front.
 //
+// You can convert coordinates from screen coordinates to page coordinates using
+// |FPDF_DeviceToPage|.
 DLLEXPORT int STDCALL
 FPDFLink_GetLinkZOrderAtPoint(FPDF_PAGE page, double x, double y);
 
-// Function: FPDFLink_GetDest
-//          Get destination info of a link.
-// Parameters:
-//          document    -   Handle to the document.
-//          link        -   Handle to the link. Returned by
-//          FPDFLink_GetLinkAtPoint.
-// Return value:
-//          Handle to the destination. NULL if there is no destination
-//          associated with the link, in this case
-//          the application should try FPDFLink_GetAction.
+// Get destination info for |link|.
 //
+//   document - handle to the document.
+//   link     - handle to the link.
+//
+// Returns a handle to the destination, or NULL if there is no destination
+// associated with the link. In this case, you should call |FPDFLink_GetAction|
+// to retrieve the action associated with |link|.
 DLLEXPORT FPDF_DEST STDCALL FPDFLink_GetDest(FPDF_DOCUMENT document,
                                              FPDF_LINK link);
 
-// Function: FPDFLink_GetAction
-//          Get action info of a link.
-// Parameters:
-//          link        -   Handle to the link.
-// Return value:
-//          Handle to the action. NULL if there is no action associated with the
-//          link.
+// Get action info for |link|.
+//
+//   link - handle to the link.
 //
+// Returns a handle to the action associated to |link|, or NULL if no action.
 DLLEXPORT FPDF_ACTION STDCALL FPDFLink_GetAction(FPDF_LINK link);
 
-// Function: FPDFLink_Enumerate
-//          This function would enumerate all the link annotations in a single
-//          PDF page.
-// Parameters:
-//          page[in]            -   Handle to the page.
-//          startPos[in,out]    -   The start position to enumerate the link
-//          annotations, which should be specified to start from
-//                              -   0 for the first call, and would receive the
-//                              next position for enumerating to start from.
-//          linkAnnot[out]      -   Receive the link handle.
-// Return value:
-//          TRUE if succceed, else False;
+// Enumerates all the link annotations in |page|.
+//
+//   page      - handle to the page.
+//   startPos  - the start position, should initially be 0 and is updated with
+//               the next start position on return.
+//   linkAnnot - the link handle for |startPos|.
 //
+// Returns TRUE on success.
 DLLEXPORT FPDF_BOOL STDCALL FPDFLink_Enumerate(FPDF_PAGE page,
                                                int* startPos,
                                                FPDF_LINK* linkAnnot);
 
-// Function: FPDFLink_GetAnnotRect
-//          Get the annotation rectangle. (Specified by the |Rect| entry of
-//          annotation dictionary).
-// Parameters:
-//          linkAnnot[in]       -   Handle to the link annotation.
-//          rect[out]           -   The annotation rect.
-// Return value:
-//          TRUE if succceed, else False;
+// Get the rectangle for |linkAnnot|.
 //
+//   linkAnnot - handle to the link annotation.
+//   rect      - the annotation rectangle.
+//
+// Returns true on success.
 DLLEXPORT FPDF_BOOL STDCALL FPDFLink_GetAnnotRect(FPDF_LINK linkAnnot,
                                                   FS_RECTF* rect);
 
-// Function: FPDFLink_CountQuadPoints
-//          Get the count of quadrilateral points to the link annotation.
-// Parameters:
-//          linkAnnot[in]       -   Handle to the link annotation.
-// Return value:
-//          The count of quadrilateral points.
+// Get the count of quadrilateral points to the |linkAnnot|.
+//
+//   linkAnnot - handle to the link annotation.
 //
+// Returns the count of quadrilateral points.
 DLLEXPORT int STDCALL FPDFLink_CountQuadPoints(FPDF_LINK linkAnnot);
 
-/* _FS_DEF_STRUCTURE_QUADPOINTSF_ */
-#ifndef _FS_DEF_STRUCTURE_QUADPOINTSF_
-#define _FS_DEF_STRUCTURE_QUADPOINTSF_
-typedef struct _FS_QUADPOINTSF {
-  FS_FLOAT x1;
-  FS_FLOAT y1;
-  FS_FLOAT x2;
-  FS_FLOAT y2;
-  FS_FLOAT x3;
-  FS_FLOAT y3;
-  FS_FLOAT x4;
-  FS_FLOAT y4;
-} FS_QUADPOINTSF;
-#endif /* _FS_DEF_STRUCTURE_QUADPOINTSF_ */
-
-// Function: FPDFLink_GetQuadPoints
-//          Get the quadrilateral points for the specified index in the link
-//          annotation.
-// Parameters:
-//          linkAnnot[in]       -   Handle to the link annotation.
-//          quadIndex[in]       -   The specified quad points index.
-//          quadPoints[out]     -   Receive the quadrilateral points.
-// Return value:
-//          True if succeed, else False.
+// Get the quadrilateral points for the specified |quadIndex| in |linkAnnot|.
 //
+//   linkAnnot  - handle to the link annotation.
+//   quadIndex  - the specified quad point index.
+//   quadPoints - receives the quadrilateral points.
+//
+// Returns true on success.
 DLLEXPORT FPDF_BOOL STDCALL FPDFLink_GetQuadPoints(FPDF_LINK linkAnnot,
                                                    int quadIndex,
                                                    FS_QUADPOINTSF* quadPoints);
 
-// Function: FPDF_GetMetaText
-//          Get a text from meta data of the document. Result is encoded in
-//          UTF-16LE.
-// Parameters:
-//          doc         -   Handle to a document
-//          tag         -   The tag for the meta data. Currently, It can be
-//          "Title", "Author",
-//                          "Subject", "Keywords", "Creator", "Producer",
-//                          "CreationDate", or "ModDate".
-//                          For detailed explanation of these tags and their
-//                          respective values,
-//                          please refer to PDF Reference 1.6, section 10.2.1,
-//                          "Document Information Dictionary".
-//          buffer      -   A buffer for output the title. Can be NULL.
-//          buflen      -   The length of the buffer, number of bytes. Can be 0.
-// Return value:
-//          Number of bytes the title consumes, including trailing zeros.
-// Comments:
-//          No matter on what platform, the title is always output in UTF-16LE
-//          encoding, which means the buffer
-//          can be regarded as an array of WORD (on Intel and compatible CPUs),
-//          each WORD represent the Unicode of
-//          a character (some special Unicode may take 2 WORDs). The string is
-//          followed by two bytes of zero
-//          indicating end of the string.
-//
-//          The return value always indicated number of bytes required for the
-//          buffer, even when there is
-//          no buffer specified, or the buffer size is less then required. In
-//          this case, the buffer will not
-//          be modified.
+// Get meta-data |tag| content from |document|.
+//
+//   doc    - handle to the document
+//   tag    - the tag to retrieve. The tag can be one of:
+//              Title, Author, Subject, Keywords, Creator, Producer,
+//              CreationDate, or ModDate.
+//            For detailed explanations of these tags and their respective
+//            values, please refer to PDF Reference 1.6, section 10.2.1,
+//            'Document Information Dictionary'.
+//   buffer - a buffer for the title. May be NULL.
+//   buflen - the length of the buffer, in bytes. May be 0.
+//
+// Returns the number of bytes in the title, including trailing zeros.
 //
+// The |buffer| is always encoded in UTF-16LE. The |buffer| is followed by two
+// bytes of zeros indicating the end of the string.  If |buflen| is less then
+// the returned length, or |buffer| is NULL, |buffer| will not be modified.
 DLLEXPORT unsigned long STDCALL FPDF_GetMetaText(FPDF_DOCUMENT doc,
                                                  FPDF_BYTESTRING tag,
                                                  void* buffer,
                                                  unsigned long buflen);
 
 #ifdef __cplusplus
-}
-#endif
+}  // extern "C"
+#endif  // __cplusplus
 
 #endif  // PUBLIC_FPDF_DOC_H_
diff --git a/public/fpdf_edit.h b/public/fpdf_edit.h
index 4ec18ee44a..acec6c0d30 100644
--- a/public/fpdf_edit.h
+++ b/public/fpdf_edit.h
@@ -11,10 +11,6 @@
 
 #include "fpdfview.h"
 
-// Define all types used in the SDK. Note they can be simply regarded as opaque
-// pointers
-// or long integer numbers.
-
 #define FPDF_ARGB(a, r, g, b)                                      \
   ((uint32_t)(((uint32_t)(b)&0xff) | (((uint32_t)(g)&0xff) << 8) | \
               (((uint32_t)(r)&0xff) << 16) | (((uint32_t)(a)&0xff) << 24)))
@@ -23,170 +19,126 @@
 #define FPDF_GetRValue(argb) ((uint8_t)((argb) >> 16))
 #define FPDF_GetAValue(argb) ((uint8_t)((argb) >> 24))
 
+// The page object constants.
+#define FPDF_PAGEOBJ_TEXT 1
+#define FPDF_PAGEOBJ_PATH 2
+#define FPDF_PAGEOBJ_IMAGE 3
+#define FPDF_PAGEOBJ_SHADING 4
+#define FPDF_PAGEOBJ_FORM 5
+
 #ifdef __cplusplus
 extern "C" {
-#endif
+#endif  // __cplusplus
 
-//////////////////////////////////////////////////////////////////////
-//
-// Document functions
+// Create a new PDF document.
 //
-//////////////////////////////////////////////////////////////////////
-
-// Function: FPDF_CreateNewDocument
-//          Create a new PDF document.
-// Parameters:
-//          None.
-// Return value:
-//          A handle to a document. If failed, NULL is returned.
+// Returns a handle to a new document, or NULL on failure.
 DLLEXPORT FPDF_DOCUMENT STDCALL FPDF_CreateNewDocument();
 
-//////////////////////////////////////////////////////////////////////
+// Create a new PDF page.
 //
-// Page functions
+//   document   - handle to document.
+//   page_index - the index of the page to create.
+//   width      - the page width.
+//   height     - the page height.
 //
-//////////////////////////////////////////////////////////////////////
-
-// Function: FPDFPage_New
-//          Construct an empty page.
-// Parameters:
-//          document    -   Handle to document. Returned by FPDF_LoadDocument
-//          and FPDF_CreateNewDocument.
-//          page_index  -   The index of a page.
-//          width       -   The page width.
-//          height      -   The page height.
-// Return value:
-//          The handle to the page.
-// Comments:
-//          Loaded page can be deleted by FPDFPage_Delete.
+// Returns the handle to the new page.
+//
+// The page should be deleted with |FPDFPage_Delete| when finished.
 DLLEXPORT FPDF_PAGE STDCALL FPDFPage_New(FPDF_DOCUMENT document,
                                          int page_index,
                                          double width,
                                          double height);
 
-// Function: FPDFPage_Delete
-//          Delete a PDF page.
-// Parameters:
-//          document    -   Handle to document. Returned by FPDF_LoadDocument
-//          and FPDF_CreateNewDocument.
-//          page_index  -   The index of a page.
-// Return value:
-//          None.
+// Delete the page at |page_index|.
+//
+//   document   - handle to document.
+//   page_index - the index of the page to delete.
 DLLEXPORT void STDCALL FPDFPage_Delete(FPDF_DOCUMENT document, int page_index);
 
-// Function: FPDFPage_GetRotation
-//          Get the page rotation. One of following values will be returned:
-//          0(0), 1(90), 2(180), 3(270).
-// Parameters:
-//          page        -   Handle to a page. Returned by FPDFPage_New or
-//          FPDF_LoadPage.
-// Return value:
-//          The PDF page rotation.
-// Comment:
-//          The PDF page rotation is rotated clockwise.
+// Get the rotation of |page|.
+//
+//   page - handle to a page
+//
+// Returns one of the following indicating the page rotation:
+//   0 - No rotation.
+//   1 - Rotated 90 degrees clockwise.
+//   2 - Rotated 180 degrees clockwise.
+//   3 - Rotated 270 degrees clockwise.
 DLLEXPORT int STDCALL FPDFPage_GetRotation(FPDF_PAGE page);
 
-// Function: FPDFPage_SetRotation
-//          Set page rotation. One of following values will be set: 0(0), 1(90),
-//          2(180), 3(270).
-// Parameters:
-//          page        -   Handle to a page. Returned by FPDFPage_New or
-//          FPDF_LoadPage.
-//          rotate      -   The value of the PDF page rotation.
-// Return value:
-//          None.
-// Comment:
-//          The PDF page rotation is rotated clockwise.
+// Set rotation for |page|.
 //
+//   page   - handle to a page.
+//   rotate - the rotation value, one of:
+//              0 - No rotation.
+//              1 - Rotated 90 degrees clockwise.
+//              2 - Rotated 180 degrees clockwise.
+//              3 - Rotated 270 degrees clockwise.
 DLLEXPORT void STDCALL FPDFPage_SetRotation(FPDF_PAGE page, int rotate);
 
-// Function: FPDFPage_InsertObject
-//          Insert an object to the page. The page object is automatically
-//          freed.
-// Parameters:
-//          page        -   Handle to a page. Returned by FPDFPage_New or
-//          FPDF_LoadPage.
-//          page_obj    -   Handle to a page object. Returned by
-//          FPDFPageObj_NewTextObj,FPDFPageObj_NewTextObjEx and
-//                          FPDFPageObj_NewPathObj.
-// Return value:
-//          None.
+// Insert |page_obj| into |page|.
+//
+//   page     - handle to a page
+//   page_obj - handle to a page object. The |page_obj| will be automatically
+//              freed.
 DLLEXPORT void STDCALL FPDFPage_InsertObject(FPDF_PAGE page,
                                              FPDF_PAGEOBJECT page_obj);
 
-// Function: FPDFPage_CountObject
-//          Get number of page objects inside the page.
-// Parameters:
-//          page        -   Handle to a page. Returned by FPDFPage_New or
-//          FPDF_LoadPage.
-// Return value:
-//          The number of the page object.
+// Get number of page objects inside |page|.
+//
+//   page - handle to a page.
+//
+// Returns the number of objects in |page|.
 DLLEXPORT int STDCALL FPDFPage_CountObject(FPDF_PAGE page);
 
-// Function: FPDFPage_GetObject
-//          Get page object by index.
-// Parameters:
-//          page        -   Handle to a page. Returned by FPDFPage_New or
-//          FPDF_LoadPage.
-//          index       -   The index of a page object.
-// Return value:
-//          The handle of the page object. Null for failed.
+// Get object in |page| at |index|.
+//
+//   page  - handle to a page.
+//   index - the index of a page object.
+//
+// Returns the handle to the page object, or NULL on failed.
 DLLEXPORT FPDF_PAGEOBJECT STDCALL FPDFPage_GetObject(FPDF_PAGE page, int index);
 
-// Function: FPDFPage_HasTransparency
-//          Check that whether the content of specified PDF page contains
-//          transparency.
-// Parameters:
-//          page        -   Handle to a page. Returned by FPDFPage_New or
-//          FPDF_LoadPage.
-// Return value:
-//          TRUE means that the PDF page does contains transparency.
-//          Otherwise, returns FALSE.
+// Checks if |page| contains transparency.
+//
+//   page - handle to a page.
+//
+// Returns TRUE if |page| contains transparency.
 DLLEXPORT FPDF_BOOL STDCALL FPDFPage_HasTransparency(FPDF_PAGE page);
 
-// Function: FPDFPage_GenerateContent
-//          Generate PDF Page content.
-// Parameters:
-//          page        -   Handle to a page. Returned by FPDFPage_New or
-//          FPDF_LoadPage.
-// Return value:
-//          True if successful, false otherwise.
-// Comment:
-//          Before you save the page to a file, or reload the page, you must
-//          call the FPDFPage_GenerateContent function.
-//          Or the changed information will be lost.
+// Generate the content of |page|.
+//
+//   page - handle to a page.
+//
+// Returns TRUE on success.
+//
+// Before you save the page to a file, or reload the page, you must call
+// |FPDFPage_GenerateContent| or any changes to |page| will be lost.
 DLLEXPORT FPDF_BOOL STDCALL FPDFPage_GenerateContent(FPDF_PAGE page);
 
-//////////////////////////////////////////////////////////////////////
+// Checks if |pageObject| contains transparency.
 //
-// Page Object functions
+//   pageObject - handle to a page object.
 //
-//////////////////////////////////////////////////////////////////////
-
-// Function: FPDFPageObj_HasTransparency
-//          Check that whether the specified PDF page object contains
-//          transparency.
-// Parameters:
-//          pageObject  -   Handle to a page object.
-// Return value:
-//          TRUE means that the PDF page object does contains transparency.
-//          Otherwise, returns FALSE.
+// Returns TRUE if |pageObject| contains transparency.
 DLLEXPORT FPDF_BOOL STDCALL
 FPDFPageObj_HasTransparency(FPDF_PAGEOBJECT pageObject);
 
-// Function: FPDFPageObj_Transform
-//          Transform (scale, rotate, shear, move) page object.
-// Parameters:
-//          page_object -   Handle to a page object. Returned by
-//          FPDFPageObj_NewImageObj.
-//          a           -   The coefficient "a" of the matrix.
-//          b           -   The coefficient "b" of the matrix.
-//          c           -   The coefficient "c" of the matrix.
-//          d           -   The coefficient "d" of the matrix.
-//          e           -   The coefficient "e" of the matrix.
-//          f           -   The coefficient "f" of the matrix.
-// Return value:
-//          None.
+// Transform |pageObject| by the given matrix.
+//
+//   page_object - handle to a page object.
+//   a           - matrix value.
+//   b           - matrix value.
+//   c           - matrix value.
+//   d           - matrix value.
+//   e           - matrix value.
+//   f           - matrix value.
+//
+// The matrix is composed as:
+//   |a c e|
+//   |b d f|
+// and can be used to scale, rotate, shear and translate the |page_object|.
 DLLEXPORT void STDCALL FPDFPageObj_Transform(FPDF_PAGEOBJECT page_object,
                                              double a,
                                              double b,
@@ -195,18 +147,20 @@ DLLEXPORT void STDCALL FPDFPageObj_Transform(FPDF_PAGEOBJECT page_object,
                                              double e,
                                              double f);
 
-// Function: FPDFPage_TransformAnnots
-//          Transform (scale, rotate, shear, move) all annots in a page.
-// Parameters:
-//          page        -   Handle to a page.
-//          a           -   The coefficient "a" of the matrix.
-//          b           -   The coefficient "b" of the matrix.
-//          c           -   The coefficient "c" of the matrix.
-//          d           -   The coefficient "d" of the matrix.
-//          e           -   The coefficient "e" of the matrix.
-//          f           -   The coefficient "f" of the matrix.
-// Return value:
-//          None.
+// Transform all annotations in |page|.
+//
+//   page - handle to a page.
+//   a    - matrix value.
+//   b    - matrix value.
+//   c    - matrix value.
+//   d    - matrix value.
+//   e    - matrix value.
+//   f    - matrix value.
+//
+// The matrix is composed as:
+//   |a c e|
+//   |b d f|
+// and can be used to scale, rotate, shear and translate the |page| annotations.
 DLLEXPORT void STDCALL FPDFPage_TransformAnnots(FPDF_PAGE page,
                                                 double a,
                                                 double b,
@@ -215,66 +169,50 @@ DLLEXPORT void STDCALL FPDFPage_TransformAnnots(FPDF_PAGE page,
                                                 double e,
                                                 double f);
 
-// The page object constants.
-#define FPDF_PAGEOBJ_TEXT 1
-#define FPDF_PAGEOBJ_PATH 2
-#define FPDF_PAGEOBJ_IMAGE 3
-#define FPDF_PAGEOBJ_SHADING 4
-#define FPDF_PAGEOBJ_FORM 5
-
-//////////////////////////////////////////////////////////////////////
+// Create a new image object.
 //
-// Image functions
+//   document - handle to a document.
 //
-//////////////////////////////////////////////////////////////////////
-
-// Function: FPDFPageObj_NewImgeObj
-//          Create a new Image Object.
-// Parameters:
-//          document        -   Handle to document. Returned by
-//          FPDF_LoadDocument or FPDF_CreateNewDocument function.
-// Return Value:
-//          Handle of image object.
+// Returns a handle to a new image object.
 DLLEXPORT FPDF_PAGEOBJECT STDCALL
 FPDFPageObj_NewImgeObj(FPDF_DOCUMENT document);
 
-// Function: FPDFImageObj_LoadJpegFile
-//          Load Image from a JPEG image file and then set it to an image
-//          object.
-// Parameters:
-//          pages           -   Pointers to the start of all loaded pages, could
-//          be NULL.
-//          nCount          -   Number of pages, could be 0.
-//          image_object    -   Handle of image object returned by
-//          FPDFPageObj_NewImgeObj.
-//          fileAccess      -   The custom file access handler, which specifies
-//          the JPEG image file.
-//  Return Value:
-//          TRUE if successful, FALSE otherwise.
-//  Note:
-//          The image object might already has an associated image, which is
-//          shared and cached by the loaded pages, In this case, we need to
-//          clear the cache of image for all the loaded pages.
-//          Pass pages and count to this API to clear the image cache.
+// Load an image from a JPEG image file and then set it into |image_object|.
+//
+//   pages        - pointer to the start of all loaded pages, may be NULL.
+//   nCount       - number of |pages|, may be 0.
+//   image_object - handle to an image object.
+//   fileAccess   - file access handler which specifies the JPEG image file.
+//
+// Returns TRUE on success.
+//
+// The image object might already have an associated image, which is shared and
+// cached by the loaded pages. In that case, we need to clear the cached image
+// for all the loaded pages. Pass |pages| and page count (|nCount|) to this API
+// to clear the image cache. If the image is not previously shared, or NULL is a
+// valid |pages| value.
 DLLEXPORT FPDF_BOOL STDCALL
 FPDFImageObj_LoadJpegFile(FPDF_PAGE* pages,
                           int nCount,
                           FPDF_PAGEOBJECT image_object,
                           FPDF_FILEACCESS* fileAccess);
 
-// Function: FPDFImageObj_SetMatrix
-//          Set the matrix of an image object.
-// Parameters:
-//          image_object    -   Handle of image object returned by
-//          FPDFPageObj_NewImgeObj.
-//          a               -   The coefficient "a" of the matrix.
-//          b               -   The coefficient "b" of the matrix.
-//          c               -   The coefficient "c" of the matrix.
-//          d               -   The coefficient "d" of the matrix.
-//          e               -   The coefficient "e" of the matrix.
-//          f               -   The coefficient "f" of the matrix.
-// Return value:
-//          TRUE if successful, FALSE otherwise.
+// Set the transform matrix of |image_object|.
+//
+//   image_object - handle to an image object.
+//   a            - matrix value.
+//   b            - matrix value.
+//   c            - matrix value.
+//   d            - matrix value.
+//   e            - matrix value.
+//   f            - matrix value.
+//
+// The matrix is composed as:
+//   |a c e|
+//   |b d f|
+// and can be used to scale, rotate, shear and translate the |page| annotations.
+//
+// Returns TRUE on success.
 DLLEXPORT FPDF_BOOL STDCALL FPDFImageObj_SetMatrix(FPDF_PAGEOBJECT image_object,
                                                    double a,
                                                    double b,
@@ -283,24 +221,21 @@ DLLEXPORT FPDF_BOOL STDCALL FPDFImageObj_SetMatrix(FPDF_PAGEOBJECT image_object,
                                                    double e,
                                                    double f);
 
-// Function: FPDFImageObj_SetBitmap
-//          Set the bitmap to an image object.
-// Parameters:
-//          pages           -   Pointer's to the start of all loaded pages.
-//          nCount          -   Number of pages.
-//          image_object    -   Handle of image object returned by
-//          FPDFPageObj_NewImgeObj.
-//          bitmap          -   The handle of the bitmap which you want to set
-//          it to the image object.
-// Return value:
-//          TRUE if successful, FALSE otherwise.
+// Set |bitmap| to |image_object|.
+//
+//   pages        - pointer to the start of all loaded pages, may be NULL.
+//   nCount       - number of |pages|, may be 0.
+//   image_object - handle to an image object.
+//   bitmap       - handle of the bitmap.
+//
+// Returns TRUE on success.
 DLLEXPORT FPDF_BOOL STDCALL FPDFImageObj_SetBitmap(FPDF_PAGE* pages,
                                                    int nCount,
                                                    FPDF_PAGEOBJECT image_object,
                                                    FPDF_BITMAP bitmap);
 
 #ifdef __cplusplus
-}
-#endif
+}  // extern "C"
+#endif  // __cplusplus
 
 #endif  // PUBLIC_FPDF_EDIT_H_