Fix the comments in fpdf_transformpage.h.

It is poorly formatted and some of the comments are wrong.

Change-Id: I7bfd3013223bff1ab8e943d33aa367cebcdc684b
Reviewed-on: https://pdfium-review.googlesource.com/34532
Reviewed-by: Henrique Nakashima <hnakashima@chromium.org>
Commit-Queue: Lei Zhang <thestig@chromium.org>

1 files changed, 77 insertions, 79 deletions

diff --git a/public/fpdf_transformpage.h b/public/fpdf_transformpage.h
index a6ed04a511..1b3abb6d2c 100644
--- a/public/fpdf_transformpage.h
+++ b/public/fpdf_transformpage.h
@@ -18,14 +18,14 @@ typedef void* FPDF_PAGEARCSAVER;
 typedef void* FPDF_PAGEARCLOADER;
 
 /**
-*  Set "MediaBox" entry to the page dictionary.
-* @param[in] page   - Handle to a page.
-* @param[in] left   - The left of the rectangle.
-* @param[in] bottom - The bottom of the rectangle.
-* @param[in] right  - The right of the rectangle.
-* @param[in] top    - The top of the rectangle.
-* @retval None.
-*/
+ * Set "MediaBox" entry to the page dictionary.
+ *
+ * page   - Handle to a page.
+ * left   - The left of the rectangle.
+ * bottom - The bottom of the rectangle.
+ * right  - The right of the rectangle.
+ * top    - The top of the rectangle.
+ */
 FPDF_EXPORT void FPDF_CALLCONV FPDFPage_SetMediaBox(FPDF_PAGE page,
                                                     float left,
                                                     float bottom,
@@ -33,50 +33,50 @@ FPDF_EXPORT void FPDF_CALLCONV FPDFPage_SetMediaBox(FPDF_PAGE page,
                                                     float top);
 
 /**
-*  Set "CropBox" entry to the page dictionary.
-* @param[in] page   - Handle to a page.
-* @param[in] left   - The left of the rectangle.
-* @param[in] bottom - The bottom of the rectangle.
-* @param[in] right  - The right of the rectangle.
-* @param[in] top    - The top of the rectangle.
-* @retval None.
-*/
+ * Set "CropBox" entry to the page dictionary.
+ *
+ * page   - Handle to a page.
+ * left   - The left of the rectangle.
+ * bottom - The bottom of the rectangle.
+ * right  - The right of the rectangle.
+ * top    - The top of the rectangle.
+ */
 FPDF_EXPORT void FPDF_CALLCONV FPDFPage_SetCropBox(FPDF_PAGE page,
                                                    float left,
                                                    float bottom,
                                                    float right,
                                                    float top);
 
-/**  Get "MediaBox" entry from the page dictionary.
-* @param[in] page   - Handle to a page.
-* @param[in] left   - Pointer to a double value receiving the left of the
-* rectangle.
-* @param[in] bottom - Pointer to a double value receiving the bottom of the
-* rectangle.
-* @param[in] right  - Pointer to a double value receiving the right of the
-* rectangle.
-* @param[in] top    - Pointer to a double value receiving the top of the
-* rectangle.
-* @retval True if success,else fail.
-*/
+/**
+ * Get "MediaBox" entry from the page dictionary.
+ *
+ * page   - Handle to a page.
+ * left   - Pointer to a float value receiving the left of the rectangle.
+ * bottom - Pointer to a float value receiving the bottom of the rectangle.
+ * right  - Pointer to a float value receiving the right of the rectangle.
+ * top    - Pointer to a float value receiving the top of the rectangle.
+ *
+ * On success, return true and write to the out parameters. Otherwise return
+ * false and leave the out parameters unmodified.
+ */
 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFPage_GetMediaBox(FPDF_PAGE page,
                                                          float* left,
                                                          float* bottom,
                                                          float* right,
                                                          float* top);
 
-/**  Get "CropBox" entry from the page dictionary.
-* @param[in] page   - Handle to a page.
-* @param[in] left   - Pointer to a double value receiving the left of the
-* rectangle.
-* @param[in] bottom - Pointer to a double value receiving the bottom of the
-* rectangle.
-* @param[in] right  - Pointer to a double value receiving the right of the
-* rectangle.
-* @param[in] top    - Pointer to a double value receiving the top of the
-* rectangle.
-* @retval True if success,else fail.
-*/
+/**
+ * Get "CropBox" entry from the page dictionary.
+ *
+ * page   - Handle to a page.
+ * left   - Pointer to a float value receiving the left of the rectangle.
+ * bottom - Pointer to a float value receiving the bottom of the rectangle.
+ * right  - Pointer to a float value receiving the right of the rectangle.
+ * top    - Pointer to a float value receiving the top of the rectangle.
+ *
+ * On success, return true and write to the out parameters. Otherwise return
+ * false and leave the out parameters unmodified.
+ */
 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFPage_GetCropBox(FPDF_PAGE page,
                                                         float* left,
                                                         float* bottom,
@@ -91,11 +91,12 @@ FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFPage_GetCropBox(FPDF_PAGE page,
  * If neither |matrix| or |clipRect| are provided this method returns |false|.
  * Returns |true| if transforms are applied.
  *
- * @param[in] page        - Page handle.
- * @param[in] matrix      - Transform matrix.
- * @param[in] clipRect    - Clipping rectangle.
- * @Note. This function will transform the whole page, and would take effect to
- * all the objects in the page.
+ * This function will transform the whole page, and would take effect to all the
+ * objects in the page.
+ *
+ * page        - Page handle.
+ * matrix      - Transform matrix.
+ * clipRect    - Clipping rectangle.
  */
 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV
 FPDFPage_TransFormWithClip(FPDF_PAGE page,
@@ -103,17 +104,17 @@ FPDFPage_TransFormWithClip(FPDF_PAGE page,
                            FS_RECTF* clipRect);
 
 /**
-* Transform (scale, rotate, shear, move) the clip path of page object.
-* @param[in] page_object - Handle to a page object. Returned by
-* FPDFPageObj_NewImageObj.
-* @param[in] a  - The coefficient "a" of the matrix.
-* @param[in] b  - The coefficient "b" of the matrix.
-* @param[in] c  - The coefficient "c" of the matrix.
-* @param[in] d  - The coefficient "d" of the matrix.
-* @param[in] e  - The coefficient "e" of the matrix.
-* @param[in] f  - The coefficient "f" of the matrix.
-* @retval None.
-*/
+ * Transform (scale, rotate, shear, move) the clip path of page object.
+ * 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.
+ */
 FPDF_EXPORT void FPDF_CALLCONV
 FPDFPageObj_TransformClipPath(FPDF_PAGEOBJECT page_object,
                               double a,
@@ -124,38 +125,35 @@ FPDFPageObj_TransformClipPath(FPDF_PAGEOBJECT page_object,
                               double f);
 
 /**
-* Create a new clip path, with a rectangle inserted.
-*
-* @param[in] left   - The left of the clip box.
-* @param[in] bottom - The bottom of the clip box.
-* @param[in] right  - The right of the clip box.
-* @param[in] top    - The top of the clip box.
-* @retval a handle to the clip path.
-*/
+ * Create a new clip path, with a rectangle inserted.
+ *
+ * left   - The left of the clip box.
+ * bottom - The bottom of the clip box.
+ * right  - The right of the clip box.
+ * top    - The top of the clip box.
+ */
 FPDF_EXPORT FPDF_CLIPPATH FPDF_CALLCONV FPDF_CreateClipPath(float left,
                                                             float bottom,
                                                             float right,
                                                             float top);
 
 /**
-* Destroy the clip path.
-*
-* @param[in] clipPath - A handle to the clip path.
-* Destroy the clip path.
-* @retval None.
-*/
+ * Destroy the clip path.
+ *
+ * clipPath - A handle to the clip path.
+ */
 FPDF_EXPORT void FPDF_CALLCONV FPDF_DestroyClipPath(FPDF_CLIPPATH clipPath);
 
 /**
-* Clip the page content, the page content that outside the clipping region
-* become invisible.
-*
-* @param[in] page        - A page handle.
-* @param[in] clipPath    - A handle to the clip path.
-* @Note. A clip path will be inserted before the page content stream or content
-* array. In this way, the page content will be clipped
-* by this clip path.
-*/
+ * Clip the page content, the page content that outside the clipping region
+ * become invisible.
+ *
+ * A clip path will be inserted before the page content stream or content array.
+ * In this way, the page content will be clipped by this clip path.
+ *
+ * page        - A page handle.
+ * clipPath    - A handle to the clip path.
+ */
 FPDF_EXPORT void FPDF_CALLCONV FPDFPage_InsertClipPath(FPDF_PAGE page,
                                                        FPDF_CLIPPATH clipPath);