Cleanup fpdf_edit.h and fpdf_doc.h documentation.

public/fpdf_edit.h

 // Copyright 2014 PDFium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com
 
 #ifndef PUBLIC_FPDF_EDIT_H_
 #define PUBLIC_FPDF_EDIT_H_
 
 #include <stdint.h>
 
 #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)))
 #define FPDF_GetBValue(argb) ((uint8_t)(argb))
 #define FPDF_GetGValue(argb) ((uint8_t)(((uint16_t)(argb)) >> 8))
 #define FPDF_GetRValue(argb) ((uint8_t)((argb) >> 16))
 #define FPDF_GetAValue(argb) ((uint8_t)((argb) >> 24))
 
+// TODO(dsinclair): What are these for?

[Tom Sepez, 2016/03/24 18:32:15]

Nah, let's not check in this TODO

[dsinclair, 2016/03/25 02:06:09]

Done.

+// 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
 
-//////////////////////////////////////////////////////////////////////
+// Create a new PDF document.
 //
-// Document functions
-//
-//////////////////////////////////////////////////////////////////////
-
-// 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, 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, 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,
                                              double c,
                                              double d,
                                              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,
                                                 double c,
                                                 double d,
                                                 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.

[Tom Sepez, 2016/03/24 18:32:15]

nit: false otherwise just to be pedantic.  Several places.

[dsinclair, 2016/03/25 02:06:09]

Acknowledged.

+//
+// 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, 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,
                                                    double c,
                                                    double d,
                                                    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.
+//
+// TODO(dsinclair): Does this have the same cache clearing requirements as

[Tom Sepez, 2016/03/24 18:32:15]

nit: let's not commit this todo either.

[dsinclair, 2016/03/25 02:06:09]

Done.

+//                  FPDFImageObj_LoadJpegFile.
 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_