Fix some whitespace in public header formatting
Presumably mangled by clang-format some time in the past.
- Prevent clang-format from doing this again.
- Replace some references to Foxit with PDFium.
- Remove some doxy-style punctuation.
Change-Id: Ia57cd69a4357e1a579316dfe333c20b9e857f3a6
Reviewed-on: https://pdfium-review.googlesource.com/c/pdfium/+/64192
Reviewed-by: Lei Zhang <thestig@chromium.org>
Commit-Queue: Tom Sepez <tsepez@chromium.org>
diff --git a/public/fpdf_progressive.h b/public/fpdf_progressive.h
index 1d7495a..99803b8 100644
--- a/public/fpdf_progressive.h
+++ b/public/fpdf_progressive.h
@@ -7,6 +7,7 @@
#ifndef PUBLIC_FPDF_PROGRESSIVE_H_
#define PUBLIC_FPDF_PROGRESSIVE_H_
+// clang-format off
// NOLINTNEXTLINE(build/include)
#include "fpdfview.h"
@@ -22,24 +23,23 @@
// IFPDF_RENDERINFO interface.
typedef struct _IFSDK_PAUSE {
- /**
- * Version number of the interface. Currently must be 1.
- **/
+ /*
+ * Version number of the interface. Currently must be 1.
+ */
int version;
/*
- * Method: NeedToPauseNow
- * Check if we need to pause a progressive process now.
- * Interface Version:
- * 1
- * Implementation Required:
- * yes
- * Parameters:
- * pThis - Pointer to the interface structure itself
- * Return Value:
- * Non-zero for pause now, 0 for continue.
- *
- */
+ * Method: NeedToPauseNow
+ * Check if we need to pause a progressive process now.
+ * Interface Version:
+ * 1
+ * Implementation Required:
+ * yes
+ * Parameters:
+ * pThis - Pointer to the interface structure itself
+ * Return Value:
+ * Non-zero for pause now, 0 for continue.
+ */
FPDF_BOOL (*NeedToPauseNow)(struct _IFSDK_PAUSE* pThis);
// A user defined data pointer, used by user's application. Can be NULL.
@@ -51,28 +51,25 @@
// progressively.
// Parameters:
// bitmap - Handle to the device independent bitmap (as the
-// output buffer).
-// Bitmap handle can be created by FPDFBitmap_Create
-// function.
-// page - Handle to the page. Returned by FPDF_LoadPage
-// function.
+// output buffer). Bitmap handle can be created by
+// FPDFBitmap_Create().
+// page - Handle to the page, as returned by FPDF_LoadPage().
// start_x - Left pixel position of the display area in the
-// bitmap coordinate.
+// bitmap coordinates.
// start_y - Top pixel position of the display area in the bitmap
-// coordinate.
+// coordinates.
// size_x - Horizontal size (in pixels) for displaying the page.
// size_y - Vertical size (in pixels) for displaying the page.
// rotate - Page orientation: 0 (normal), 1 (rotated 90 degrees
-// clockwise),
-// 2 (rotated 180 degrees), 3 (rotated 90 degrees
-// counter-clockwise).
+// clockwise), 2 (rotated 180 degrees), 3 (rotated 90
+// degrees counter-clockwise).
// flags - 0 for normal display, or combination of flags
// defined in fpdfview.h. With FPDF_ANNOT flag, it
// renders all annotations that does not require
// user-interaction, which are all annotations except
// widget and popup annotations.
// pause - The IFSDK_PAUSE interface.A callback mechanism
-// allowing the page rendering process
+// allowing the page rendering process
// Return value:
// Rendering Status. See flags for progressive process status for the
// details.
@@ -90,12 +87,11 @@
// Function: FPDF_RenderPage_Continue
// Continue rendering a PDF page.
// Parameters:
-// page - Handle to the page. Returned by FPDF_LoadPage
-// function.
-// pause - The IFSDK_PAUSE interface.A callback mechanism
-// allowing the page rendering process
-// to be paused before it's finished. This can be NULL
-// if you don't want to pause.
+// page - Handle to the page, as returned by FPDF_LoadPage().
+// pause - The IFSDK_PAUSE interface (a callback mechanism
+// allowing the page rendering process to be paused
+// before it's finished). This can be NULL if you
+// don't want to pause.
// Return value:
// The rendering status. See flags for progressive process status for
// the details.
@@ -107,10 +103,9 @@
// called after finishing rendering or
// cancel the rendering.
// Parameters:
-// page - Handle to the page. Returned by FPDF_LoadPage
-// function.
+// page - Handle to the page, as returned by FPDF_LoadPage().
// Return value:
-// NULL
+// None.
FPDF_EXPORT void FPDF_CALLCONV FPDF_RenderPage_Close(FPDF_PAGE page);
#ifdef __cplusplus
diff --git a/public/fpdf_save.h b/public/fpdf_save.h
index 6ffca52..527d942 100644
--- a/public/fpdf_save.h
+++ b/public/fpdf_save.h
@@ -7,6 +7,7 @@
#ifndef PUBLIC_FPDF_SAVE_H_
#define PUBLIC_FPDF_SAVE_H_
+// clang-format off
// NOLINTNEXTLINE(build/include)
#include "fpdfview.h"
@@ -21,7 +22,6 @@
//
int version;
- //
// Method: WriteBlock
// Output a block of data in your custom way.
// Interface Version:
@@ -36,24 +36,21 @@
// size - The size of the buffer.
// Return value:
// Should be non-zero if successful, zero for error.
- //
int (*WriteBlock)(struct FPDF_FILEWRITE_* pThis,
const void* pData,
unsigned long size);
} FPDF_FILEWRITE;
-/** @brief Incremental. */
+ // Flags for FPDF_SaveAsCopy()
#define FPDF_INCREMENTAL 1
-/** @brief No Incremental. */
#define FPDF_NO_INCREMENTAL 2
-/** @brief Remove security. */
#define FPDF_REMOVE_SECURITY 3
// Function: FPDF_SaveAsCopy
// Saves the copy of specified document in custom way.
// Parameters:
-// document - Handle to document. Returned by
-// FPDF_LoadDocument and FPDF_CreateNewDocument.
+// document - Handle to document, as returned by
+// FPDF_LoadDocument() or FPDF_CreateNewDocument().
// pFileWrite - A pointer to a custom file write structure.
// flags - The creating flags.
// Return value:
@@ -64,14 +61,14 @@
FPDF_DWORD flags);
// Function: FPDF_SaveWithVersion
-// Same as function ::FPDF_SaveAsCopy, except the file version of the
-// saved document could be specified by user.
+// Same as FPDF_SaveAsCopy(), except the file version of the
+// saved document can be specified by the caller.
// Parameters:
// document - Handle to document.
// pFileWrite - A pointer to a custom file write structure.
// flags - The creating flags.
// fileVersion - The PDF file version. File version: 14 for 1.4,
-// 15 for 1.5, ...
+// 15 for 1.5, ...
// Return value:
// TRUE if succeed, FALSE if failed.
//
diff --git a/public/fpdf_structtree.h b/public/fpdf_structtree.h
index 2e86ae6..a8083d5 100644
--- a/public/fpdf_structtree.h
+++ b/public/fpdf_structtree.h
@@ -7,6 +7,7 @@
#ifndef PUBLIC_FPDF_STRUCTTREE_H_
#define PUBLIC_FPDF_STRUCTTREE_H_
+// clang-format off
// NOLINTNEXTLINE(build/include)
#include "fpdfview.h"
@@ -17,28 +18,27 @@
// Function: FPDF_StructTree_GetForPage
// Get the structure tree for a page.
// Parameters:
-// page - Handle to the page. Returned by FPDF_LoadPage
-// function.
+// page - Handle to the page, as returned by FPDF_LoadPage().
// Return value:
// A handle to the structure tree or NULL on error.
FPDF_EXPORT FPDF_STRUCTTREE FPDF_CALLCONV
FPDF_StructTree_GetForPage(FPDF_PAGE page);
// Function: FPDF_StructTree_Close
-// Release the resource allocate by FPDF_StructTree_GetForPage.
+// Release a resource allocated by FPDF_StructTree_GetForPage().
// Parameters:
-// struct_tree - Handle to the struct tree. Returned by
-// FPDF_StructTree_LoadPage function.
+// struct_tree - Handle to the structure tree, as returned by
+// FPDF_StructTree_LoadPage().
// Return value:
-// NULL
+// None.
FPDF_EXPORT void FPDF_CALLCONV
FPDF_StructTree_Close(FPDF_STRUCTTREE struct_tree);
// Function: FPDF_StructTree_CountChildren
// Count the number of children for the structure tree.
// Parameters:
-// struct_tree - Handle to the struct tree. Returned by
-// FPDF_StructTree_LoadPage function.
+// struct_tree - Handle to the structure tree, as returned by
+// FPDF_StructTree_LoadPage().
// Return value:
// The number of children, or -1 on error.
FPDF_EXPORT int FPDF_CALLCONV
@@ -47,8 +47,8 @@
// Function: FPDF_StructTree_GetChildAtIndex
// Get a child in the structure tree.
// Parameters:
-// struct_tree - Handle to the struct tree. Returned by
-// FPDF_StructTree_LoadPage function.
+// struct_tree - Handle to the structure tree, as returned by
+// FPDF_StructTree_LoadPage().
// index - The index for the child, 0-based.
// Return value:
// The child at the n-th index or NULL on error.
diff --git a/public/fpdf_sysfontinfo.h b/public/fpdf_sysfontinfo.h
index 49302c8..30cdd44 100644
--- a/public/fpdf_sysfontinfo.h
+++ b/public/fpdf_sysfontinfo.h
@@ -7,6 +7,7 @@
#ifndef PUBLIC_FPDF_SYSFONTINFO_H_
#define PUBLIC_FPDF_SYSFONTINFO_H_
+// clang-format off
// NOLINTNEXTLINE(build/include)
#include "fpdfview.h"
@@ -33,84 +34,84 @@
extern "C" {
#endif
-/**
+/*
* Interface: FPDF_SYSFONTINFO
* Interface for getting system font information and font mapping
*/
typedef struct _FPDF_SYSFONTINFO {
- /**
+ /*
* Version number of the interface. Currently must be 1.
- **/
+ */
int version;
- /**
+ /*
* Method: Release
* Give implementation a chance to release any data after the
- * interface is no longer used
+ * interface is no longer used.
* Interface Version:
* 1
* Implementation Required:
* No
- * Comments:
- * Called by Foxit SDK during the final cleanup process.
* Parameters:
* pThis - Pointer to the interface structure itself
* Return Value:
* None
+ * Comments:
+ * Called by PDFium during the final cleanup process.
*/
void (*Release)(struct _FPDF_SYSFONTINFO* pThis);
- /**
+ /*
* Method: EnumFonts
* Enumerate all fonts installed on the system
* Interface Version:
* 1
* Implementation Required:
* No
- * Comments:
- * Implementation should call FPDF_AddIntalledFont() function for
- * each font found.
- * Only TrueType/OpenType and Type1 fonts are accepted by Foxit SDK.
* Parameters:
* pThis - Pointer to the interface structure itself
* pMapper - An opaque pointer to internal font mapper, used
- * when calling FPDF_AddInstalledFont
+ * when calling FPDF_AddInstalledFont().
* Return Value:
* None
+ * Comments:
+ * Implementations should call FPDF_AddIntalledFont() function for
+ * each font found. Only TrueType/OpenType and Type1 fonts are accepted
+ * by PDFium.
*/
void (*EnumFonts)(struct _FPDF_SYSFONTINFO* pThis, void* pMapper);
- /**
+ /*
* Method: MapFont
* Use the system font mapper to get a font handle from requested
- *parameters
+ * parameters.
* Interface Version:
* 1
* Implementation Required:
- * Yes only if GetFont method is not implemented.
- * Comments:
- * If the system supports native font mapper (like Windows),
- *implementation can implement this method to get a font handle.
- * Otherwise, Foxit SDK will do the mapping and then call GetFont
- *method.
- * Only TrueType/OpenType and Type1 fonts are accepted by Foxit SDK.
+ * Required if GetFont method is not implemented.
* Parameters:
* pThis - Pointer to the interface structure itself
* weight - Weight of the requested font. 400 is normal and
- *700 is bold.
+ * 700 is bold.
* bItalic - Italic option of the requested font, TRUE or
- *FALSE.
+ * FALSE.
* charset - Character set identifier for the requested font.
- *See above defined constants.
+ * See above defined constants.
* pitch_family - A combination of flags. See above defined
- *constants.
+ * constants.
* face - Typeface name. Currently use system local encoding
- *only.
+ * only.
* bExact - Obsolete: this parameter is now ignored.
* Return Value:
* An opaque pointer for font handle, or NULL if system mapping is
- *not supported.
- **/
+ * not supported.
+ * Comments:
+ * If the system supports native font mapper (like Windows),
+ * implementation can implement this method to get a font handle.
+ * Otherwise, PDFium will do the mapping and then call GetFont
+ * method. Only TrueType/OpenType and Type1 fonts are accepted
+ * by PDFium.
+ */
void* (*MapFont)(struct _FPDF_SYSFONTINFO* pThis,
int weight,
FPDF_BOOL bItalic,
@@ -119,56 +120,53 @@
const char* face,
FPDF_BOOL* bExact);
- /**
+ /*
* Method: GetFont
* Get a handle to a particular font by its internal ID
* Interface Version:
* 1
* Implementation Required:
- * Yes only if MapFont method is not implemented.
- * Comments:
- * If the system mapping not supported, Foxit SDK will do the font
- *mapping and use this method to get a font handle.
- * Parameters:
- * pThis - Pointer to the interface structure itself
- * face - Typeface name. Currently use system local encoding
- *only.
+ * Required if MapFont method is not implemented.
* Return Value:
* An opaque pointer for font handle.
- **/
+ * Parameters:
+ * pThis - Pointer to the interface structure itself
+ * face - Typeface name in system local encoding.
+ * Comments:
+ * If the system mapping not supported, PDFium will do the font
+ * mapping and use this method to get a font handle.
+ */
void* (*GetFont)(struct _FPDF_SYSFONTINFO* pThis, const char* face);
- /**
+ /*
* Method: GetFontData
* Get font data from a font
* Interface Version:
* 1
* Implementation Required:
* Yes
- * Comments:
- * Can read either full font file, or a particular TrueType/OpenType
- *table
* Parameters:
* pThis - Pointer to the interface structure itself
* hFont - Font handle returned by MapFont or GetFont method
* table - TrueType/OpenType table identifier (refer to
- *TrueType specification).
- * 0 for the whole font file.
+ * TrueType specification), or 0 for the whole file.
* buffer - The buffer receiving the font data. Can be NULL if
- *not provided
- * buf_size - Buffer size, can be zero if not provided
+ * not provided.
+ * buf_size - Buffer size, can be zero if not provided.
* Return Value:
* Number of bytes needed, if buffer not provided or not large
- *enough,
- * or number of bytes written into buffer otherwise.
- **/
+ * enough, or number of bytes written into buffer otherwise.
+ * Comments:
+ * Can read either the full font file, or a particular
+ * TrueType/OpenType table.
+ */
unsigned long (*GetFontData)(struct _FPDF_SYSFONTINFO* pThis,
void* hFont,
unsigned int table,
unsigned char* buffer,
unsigned long buf_size);
- /**
+ /*
* Method: GetFaceName
* Get face name from a font handle
* Interface Version:
@@ -179,19 +177,18 @@
* pThis - Pointer to the interface structure itself
* hFont - Font handle returned by MapFont or GetFont method
* buffer - The buffer receiving the face name. Can be NULL if
- *not provided
+ * not provided
* buf_size - Buffer size, can be zero if not provided
* Return Value:
* Number of bytes needed, if buffer not provided or not large
- *enough,
- * or number of bytes written into buffer otherwise.
- **/
+ * enough, or number of bytes written into buffer otherwise.
+ */
unsigned long (*GetFaceName)(struct _FPDF_SYSFONTINFO* pThis,
void* hFont,
char* buffer,
unsigned long buf_size);
- /**
+ /*
* Method: GetFontCharset
* Get character set information for a font handle
* Interface Version:
@@ -203,10 +200,10 @@
* hFont - Font handle returned by MapFont or GetFont method
* Return Value:
* Character set identifier. See defined constants above.
- **/
+ */
int (*GetFontCharset)(struct _FPDF_SYSFONTINFO* pThis, void* hFont);
- /**
+ /*
* Method: DeleteFont
* Delete a font handle
* Interface Version:
@@ -218,20 +215,20 @@
* hFont - Font handle returned by MapFont or GetFont method
* Return Value:
* None
- **/
+ */
void (*DeleteFont)(struct _FPDF_SYSFONTINFO* pThis, void* hFont);
} FPDF_SYSFONTINFO;
-/**
+/*
* Struct: FPDF_CharsetFontMap
* Provides the name of a font to use for a given charset value.
- **/
+ */
typedef struct FPDF_CharsetFontMap_ {
int charset; // Character Set Enum value, see FXFONT_*_CHARSET above.
const char* fontname; // Name of default font to use with that charset.
} FPDF_CharsetFontMap;
-/**
+/*
* Function: FPDF_GetDefaultTTFMap
* Returns a pointer to the default character set to TT Font name map. The
* map is an array of FPDF_CharsetFontMap structs, with its end indicated
@@ -240,71 +237,69 @@
* None.
* Return Value:
* Pointer to the Charset Font Map.
- **/
+ */
FPDF_EXPORT const FPDF_CharsetFontMap* FPDF_CALLCONV FPDF_GetDefaultTTFMap();
-/**
+/*
* Function: FPDF_AddInstalledFont
- * Add a system font to the list in Foxit SDK.
+ * Add a system font to the list in PDFium.
* Comments:
* This function is only called during the system font list building
- *process.
+ * process.
* Parameters:
* mapper - Opaque pointer to Foxit font mapper
* face - The font face name
* charset - Font character set. See above defined constants.
* Return Value:
* None.
- **/
+ */
FPDF_EXPORT void FPDF_CALLCONV FPDF_AddInstalledFont(void* mapper,
const char* face,
int charset);
-/**
+/*
* Function: FPDF_SetSystemFontInfo
- * Set the system font info interface into Foxit SDK
- * Comments:
- * Platform support implementation should implement required methods of
- *FFDF_SYSFONTINFO interface,
- * then call this function during SDK initialization process.
+ * Set the system font info interface into PDFium
* Parameters:
* pFontInfo - Pointer to a FPDF_SYSFONTINFO structure
* Return Value:
* None
- **/
+ * Comments:
+ * Platform support implementation should implement required methods of
+ * FFDF_SYSFONTINFO interface, then call this function during PDFium
+ * initialization process.
+ */
FPDF_EXPORT void FPDF_CALLCONV
FPDF_SetSystemFontInfo(FPDF_SYSFONTINFO* pFontInfo);
-/**
+/*
* Function: FPDF_GetDefaultSystemFontInfo
* Get default system font info interface for current platform
- * Comments:
- * For some platforms Foxit SDK implement a default version of system
- *font info interface.
- * The default implementation can be used in FPDF_SetSystemFontInfo
- *function.
* Parameters:
* None
* Return Value:
* Pointer to a FPDF_SYSFONTINFO structure describing the default
- *interface.
- * Or NULL if the platform doesn't have a default interface.
+ * interface, or NULL if the platform doesn't have a default interface.
* Application should call FPDF_FreeDefaultSystemFontInfo to free the
- *returned pointer.
- **/
+ * returned pointer.
+ * Comments:
+ * For some platforms, PDFium implements a default version of system
+ * font info interface. The default implementation can be passed to
+ * FPDF_SetSystemFontInfo().
+ */
FPDF_EXPORT FPDF_SYSFONTINFO* FPDF_CALLCONV FPDF_GetDefaultSystemFontInfo();
-/**
+/*
* Function: FPDF_FreeDefaultSystemFontInfo
* Free a default system font info interface
- * Comments:
- * This function should be called on the output from
- *FPDF_SetSystemFontInfo once it is no longer needed by the client.
* Parameters:
* pFontInfo - Pointer to a FPDF_SYSFONTINFO structure
* Return Value:
- * None
- **/
+ * None
+ * Comments:
+ * This function should be called on the output from
+ * FPDF_SetSystemFontInfo() once it is no longer needed.
+ */
FPDF_EXPORT void FPDF_CALLCONV
FPDF_FreeDefaultSystemFontInfo(FPDF_SYSFONTINFO* pFontInfo);
diff --git a/public/fpdf_text.h b/public/fpdf_text.h
index 7905e9f..3cce6ad 100644
--- a/public/fpdf_text.h
+++ b/public/fpdf_text.h
@@ -7,6 +7,7 @@
#ifndef PUBLIC_FPDF_TEXT_H_
#define PUBLIC_FPDF_TEXT_H_
+// clang-format off
// NOLINTNEXTLINE(build/include)
#include "fpdfview.h"
@@ -19,7 +20,7 @@
// Prepare information about all characters in a page.
// Parameters:
// page - Handle to the page. Returned by FPDF_LoadPage function
-// (in FPDFVIEW module).
+// (in FPDFVIEW module).
// Return value:
// A handle to the text page information structure.
// NULL if something goes wrong.
@@ -34,7 +35,7 @@
// structure.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// Return Value:
// None.
//
@@ -44,7 +45,7 @@
// Get number of characters in a page.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// Return value:
// Number of characters in the page. Return -1 for error.
// Generated characters, like additional space characters, new line
@@ -62,7 +63,7 @@
// Get Unicode of a character in a page.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// index - Zero-based index of the character.
// Return value:
// The Unicode of the particular character.
@@ -77,12 +78,12 @@
// Get the font size of a particular character.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// index - Zero-based index of the character.
// Return value:
// The font size of the particular character, measured in points (about
-// 1/72 inch).
-// This is the typographic size of the font (so called "em size").
+// 1/72 inch). This is the typographic size of the font (so called
+// "em size").
//
FPDF_EXPORT double FPDF_CALLCONV FPDFText_GetFontSize(FPDF_TEXTPAGE text_page,
int index);
@@ -92,19 +93,20 @@
// Get the font name and flags of a particular character.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// index - Zero-based index of the character.
// buffer - A buffer receiving the font name.
// buflen - The length of |buffer| in bytes.
// flags - Optional pointer to an int receiving the font flags.
-// These flags should be interpreted per PDF spec 1.7 Section 5.7.1
-// Font Descriptor Flags.
+// These flags should be interpreted per PDF spec 1.7
+// Section 5.7.1 Font Descriptor Flags.
// Return value:
// On success, return the length of the font name, including the
// trailing NUL character, in bytes. If this length is less than or
// equal to |length|, |buffer| is set to the font name, |flags| is
// set to the font flags. |buffer| is in UTF-8 encoding. Return 0 on
// failure.
+//
FPDF_EXPORT unsigned long FPDF_CALLCONV
FPDFText_GetFontInfo(FPDF_TEXTPAGE text_page,
int index,
@@ -139,6 +141,7 @@
// FPDF_TEXT_RENDERMODE. If |text_page| is invalid, if |index| is out
// of bounds, or if the text object is undefined, then return
// FPDF_TEXTRENDERMODE_UNKNOWN.
+//
FPDF_EXPORT FPDF_TEXT_RENDERMODE FPDF_CALLCONV
FPDFText_GetTextRenderMode(FPDF_TEXTPAGE text_page, int index);
@@ -207,6 +210,7 @@
// On success, return the angle value in radian. Value will always be
// greater or equal to 0. If |text_page| is invalid, or if |index| is
// out of bounds, then return -1.
+//
FPDF_EXPORT float FPDF_CALLCONV FPDFText_GetCharAngle(FPDF_TEXTPAGE text_page,
int index);
@@ -214,16 +218,16 @@
// Get bounding box of a particular character.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// index - Zero-based index of the character.
// left - Pointer to a double number receiving left position
-// of the character box.
+// of the character box.
// right - Pointer to a double number receiving right position
-// of the character box.
+// of the character box.
// bottom - Pointer to a double number receiving bottom position
-// of the character box.
+// of the character box.
// top - Pointer to a double number receiving top position of
-// the character box.
+// the character box.
// Return Value:
// On success, return TRUE and fill in |left|, |right|, |bottom|, and
// |top|. If |text_page| is invalid, or if |index| is out of bounds,
@@ -262,12 +266,12 @@
// Get origin of a particular character.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// index - Zero-based index of the character.
// x - Pointer to a double number receiving x coordinate of
-// the character origin.
+// the character origin.
// y - Pointer to a double number receiving y coordinate of
-// the character origin.
+// the character origin.
// Return Value:
// Whether the call succeeded. If false, x and y are unchanged.
// Comments:
@@ -284,18 +288,17 @@
// page.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// x - X position in PDF "user space".
// y - Y position in PDF "user space".
// xTolerance - An x-axis tolerance value for character hit
-// detection, in point unit.
+// detection, in point units.
// yTolerance - A y-axis tolerance value for character hit
-// detection, in point unit.
+// detection, in point units.
// Return Value:
// The zero-based index of the character at, or nearby the point (x,y).
// If there is no character at or nearby the point, return value will
-// be -1.
-// If an error occurs, -3 will be returned.
+// be -1. If an error occurs, -3 will be returned.
//
FPDF_EXPORT int FPDF_CALLCONV
FPDFText_GetCharIndexAtPos(FPDF_TEXTPAGE text_page,
@@ -308,13 +311,13 @@
// Extract unicode text string from the page.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// start_index - Index for the start characters.
// count - Number of characters to be extracted.
// result - A buffer (allocated by application) receiving the
-// extracted unicodes.
-// The size of the buffer must be able to hold the
-// number of characters plus a terminator.
+// extracted unicodes. The size of the buffer must be
+// able to hold the number of characters plus a
+// terminator.
// Return Value:
// Number of characters written into the result buffer, including the
// trailing terminator.
@@ -330,18 +333,16 @@
// Count number of rectangular areas occupied by a segment of texts.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// start_index - Index for the start characters.
// count - Number of characters.
// Return value:
// Number of rectangles. Zero for error.
// Comments:
// This function, along with FPDFText_GetRect can be used by
-// applications to detect the position
-// on the page for a text segment, so proper areas can be highlighted
-// or something.
-// FPDFTEXT will automatically merge small character boxes into bigger
-// one if those characters
+// applications to detect the position on the page for a text segment,
+// so proper areas can be highlighted. FPDFTEXT will automatically
+// merge small character boxes into bigger one if those characters
// are on the same line and use same font settings.
//
FPDF_EXPORT int FPDF_CALLCONV FPDFText_CountRects(FPDF_TEXTPAGE text_page,
@@ -353,16 +354,16 @@
// FPDFText_CountRects.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// rect_index - Zero-based index for the rectangle.
// left - Pointer to a double value receiving the rectangle
-// left boundary.
+// left boundary.
// top - Pointer to a double value receiving the rectangle
-// top boundary.
+// top boundary.
// right - Pointer to a double value receiving the rectangle
-// right boundary.
+// right boundary.
// bottom - Pointer to a double value receiving the rectangle
-// bottom boundary.
+// bottom boundary.
// Return Value:
// On success, return TRUE and fill in |left|, |top|, |right|, and
// |bottom|. If |text_page| is invalid then return FALSE, and the out
@@ -381,23 +382,21 @@
// Extract unicode text within a rectangular boundary on the page.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// left - Left boundary.
// top - Top boundary.
// right - Right boundary.
// bottom - Bottom boundary.
// buffer - A unicode buffer.
// buflen - Number of characters (not bytes) for the buffer,
-// excluding an additional terminator.
+// excluding an additional terminator.
// Return Value:
// If buffer is NULL or buflen is zero, return number of characters
-// (not bytes) of text present within
-// the rectangle, excluding a terminating NUL. Generally you should
-// pass a buffer at least one larger
-// than this if you want a terminating NUL, which will be provided if
-// space is available.
-// Otherwise, return number of characters copied into the buffer,
-// including the terminating NUL
+// (not bytes) of text present within the rectangle, excluding a
+// terminating NUL. Generally you should pass a buffer at least one
+// larger than this if you want a terminating NUL, which will be
+// provided if space is available. Otherwise, return number of
+// characters copied into the buffer, including the terminating NUL
// when space for it is available.
// Comment:
// If the buffer is too small, as much text as will fit is copied into
@@ -424,7 +423,7 @@
// Start a search.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// findwhat - A unicode match pattern.
// flags - Option flags.
// start_index - Start from this character. -1 for end of the page.
@@ -442,7 +441,7 @@
// Search in the direction from page start to end.
// Parameters:
// handle - A search context handle returned by
-// FPDFText_FindStart.
+// FPDFText_FindStart.
// Return Value:
// Whether a match is found.
//
@@ -452,7 +451,7 @@
// Search in the direction from page end to start.
// Parameters:
// handle - A search context handle returned by
-// FPDFText_FindStart.
+// FPDFText_FindStart.
// Return Value:
// Whether a match is found.
//
@@ -462,7 +461,7 @@
// Get the starting character index of the search result.
// Parameters:
// handle - A search context handle returned by
-// FPDFText_FindStart.
+// FPDFText_FindStart.
// Return Value:
// Index for the starting character.
//
@@ -472,7 +471,7 @@
// Get the number of matched characters in the search result.
// Parameters:
// handle - A search context handle returned by
-// FPDFText_FindStart.
+// FPDFText_FindStart.
// Return Value:
// Number of matched characters.
//
@@ -482,7 +481,7 @@
// Release a search context.
// Parameters:
// handle - A search context handle returned by
-// FPDFText_FindStart.
+// FPDFText_FindStart.
// Return Value:
// None.
//
@@ -492,22 +491,18 @@
// Prepare information about weblinks in a page.
// Parameters:
// text_page - Handle to a text page information structure.
-// Returned by FPDFText_LoadPage function.
+// Returned by FPDFText_LoadPage function.
// Return Value:
-// A handle to the page's links information structure.
+// A handle to the page's links information structure, or
// NULL if something goes wrong.
// Comments:
// Weblinks are those links implicitly embedded in PDF pages. PDF also
-// has a type of
-// annotation called "link", FPDFTEXT doesn't deal with that kind of
-// link.
-// FPDFTEXT weblink feature is useful for automatically detecting links
-// in the page
-// contents. For example, things like "http://www.foxitsoftware.com"
-// will be detected,
-// so applications can allow user to click on those characters to
-// activate the link,
-// even the PDF doesn't come with link annotations.
+// has a type of annotation called "link" (FPDFTEXT doesn't deal with
+// that kind of link). FPDFTEXT weblink feature is useful for
+// automatically detecting links in the page contents. For example,
+// things like "https://www.example.com" will be detected, so
+// applications can allow user to click on those characters to activate
+// the link, even the PDF doesn't come with link annotations.
//
// FPDFLink_CloseWebLinks must be called to release resources.
//
diff --git a/public/fpdfview.h b/public/fpdfview.h
index 7223e5a..901d7db 100644
--- a/public/fpdfview.h
+++ b/public/fpdfview.h
@@ -10,6 +10,8 @@
#ifndef PUBLIC_FPDFVIEW_H_
#define PUBLIC_FPDFVIEW_H_
+// clang-format off
+
#include <stddef.h>
#if defined(_WIN32) && !defined(__WINDOWS__)
@@ -394,87 +396,98 @@
void* m_Param;
} FPDF_FILEACCESS;
-/**
+/*
* Structure for file reading or writing (I/O).
*
* Note: This is a handler and should be implemented by callers,
* and is only used from XFA.
*/
typedef struct FPDF_FILEHANDLER_ {
- /**
- * @brief User-defined data.
- * @note Callers can use this field to track controls.
+ /*
+ * User-defined data.
+ * Note: Callers can use this field to track controls.
*/
void* clientData;
- /**
- * @brief Callback function to release the current file stream object.
+
+ /*
+ * Callback function to release the current file stream object.
*
- * @param[in] clientData Pointer to user-defined data.
- *
- * @return None.
+ * Parameters:
+ * clientData - Pointer to user-defined data.
+ * Returns:
+ * None.
*/
void (*Release)(void* clientData);
- /**
- * @brief Callback function to retrieve the current file stream size.
+
+ /*
+ * Callback function to retrieve the current file stream size.
*
- * @param[in] clientData Pointer to user-defined data.
- *
- * @return Size of file stream.
+ * Parameters:
+ * clientData - Pointer to user-defined data.
+ * Returns:
+ * Size of file stream.
*/
FPDF_DWORD (*GetSize)(void* clientData);
- /**
- * @brief Callback function to read data from the current file stream.
+
+ /*
+ * Callback function to read data from the current file stream.
*
- * @param[in] clientData Pointer to user-defined data.
- * @param[in] offset Offset position starts from the beginning of file
- * stream. This parameter indicates reading position.
- * @param[in] buffer Memory buffer to store data which are read from
- * file stream. This parameter should not be <b>NULL</b>.
- * @param[in] size Size of data which should be read from file
- * stream, in bytes. The buffer indicated by the parameter <i>buffer</i>
- * should be enough to store specified data.
- *
- * @return 0 for success, other value for failure.
+ * Parameters:
+ * clientData - Pointer to user-defined data.
+ * offset - Offset position starts from the beginning of file
+ * stream. This parameter indicates reading position.
+ * buffer - Memory buffer to store data which are read from
+ * file stream. This parameter should not be NULL.
+ * size - Size of data which should be read from file stream,
+ * in bytes. The buffer indicated by |buffer| must be
+ * large enough to store specified data.
+ * Returns:
+ * 0 for success, other value for failure.
*/
FPDF_RESULT (*ReadBlock)(void* clientData,
FPDF_DWORD offset,
void* buffer,
FPDF_DWORD size);
- /**
- * @brief Callback function to write data into the current file stream.
+
+ /*
+ * Callback function to write data into the current file stream.
*
- * @param[in] clientData Pointer to user-defined data.
- * @param[in] offset Offset position starts from the beginning of file
- * stream. This parameter indicates writing position.
- * @param[in] buffer Memory buffer contains data which is written into
- * file stream. This parameter should not be <b>NULL</b>.
- * @param[in] size Size of data which should be written into file
- * stream, in bytes.
- *
- * @return 0 for success, other value for failure.
+ * Parameters:
+ * clientData - Pointer to user-defined data.
+ * offset - Offset position starts from the beginning of file
+ * stream. This parameter indicates writing position.
+ * buffer - Memory buffer contains data which is written into
+ * file stream. This parameter should not be NULL.
+ * size - Size of data which should be written into file
+ * stream, in bytes.
+ * Returns:
+ * 0 for success, other value for failure.
*/
FPDF_RESULT (*WriteBlock)(void* clientData,
FPDF_DWORD offset,
const void* buffer,
FPDF_DWORD size);
- /**
- * @brief Callback function to flush all internal accessing buffers.
+ /*
+ * Callback function to flush all internal accessing buffers.
*
- * @param[in] clientData Pointer to user-defined data.
- *
- * @return 0 for success, other value for failure.
+ * Parameters:
+ * clientData - Pointer to user-defined data.
+ * Returns:
+ * 0 for success, other value for failure.
*/
FPDF_RESULT (*Flush)(void* clientData);
- /**
- * @brief Callback function to change file size.
+
+ /*
+ * Callback function to change file size.
*
- * @details This function is called under writing mode usually. Implementer
- * can determine whether to realize it based on application requests.
- *
- * @param[in] clientData Pointer to user-defined data.
- * @param[in] size New size of file stream, in bytes.
- *
- * @return 0 for success, other value for failure.
+ * Description:
+ * This function is called under writing mode usually. Implementer
+ * can determine whether to realize it based on application requests.
+ * Parameters:
+ * clientData - Pointer to user-defined data.
+ * size - New size of file stream, in bytes.
+ * Returns:
+ * 0 for success, other value for failure.
*/
FPDF_RESULT (*Truncate)(void* clientData, FPDF_DWORD size);
} FPDF_FILEHANDLER;
