Cleanup public/fpdf_dataavail.h documentation.

public/fpdf_dataavail.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_DATAAVAIL_H_
 #define PUBLIC_FPDF_DATAAVAIL_H_
 
-#include <stddef.h>  // For size_t.
+#include <stddef.h>
 
 #include "fpdfview.h"
 
 #define PDF_LINEARIZATION_UNKNOWN -1
 #define PDF_NOT_LINEARIZED 0
 #define PDF_LINEARIZED 1
 
 #define PDF_DATA_ERROR -1
 #define PDF_DATA_NOTAVAIL 0
 #define PDF_DATA_AVAIL 1
 
 #define PDF_FORM_ERROR -1
 #define PDF_FORM_NOTAVAIL 0
 #define PDF_FORM_AVAIL 1
 #define PDF_FORM_NOTEXIST 2
 
 #ifdef __cplusplus
 extern "C" {
-#endif
+#endif  // __cplusplus
 
-/**
- * Interface: FX_FILEAVAIL
- *          Interface for checking whether the section of the file is available.
- */
+// Interface for checking whether the section of the file is available.
 typedef struct _FX_FILEAVAIL {
-  /**
-   * Version number of the interface. Currently must be 1.
-   */
+  // Version number of the interface. Must be 1.
   int version;
 
-  /**
-   * Method: IsDataAvail
-   *      Report whether the specified data section is available. A section is
-   * available only if all bytes in the section is available.
-   * Interface Version:
-   *      1
-   * Implementation Required:
-   *      Yes
-   * Parameters:
-   *      pThis       -   Pointer to the interface structure itself.
-   *      offset      -   The offset of the data section in the file.
-   *      size        -   The size of the data section
-   * Return Value:
-   *      true means the specified data section is available.
-   * Comments:
-   *      Called by Foxit SDK to check whether the data section is ready.
-   */
+  // Reports if the specified data section is available. A section is

[Tom Sepez, 2016/03/23 20:10:58]

nit: maybe add "at the present time." since this could change as stuff comes
over the wire vs. having a perpetual black hole in the file.

[dsinclair, 2016/03/23 23:35:59]

Changed to 'currently available'

+  // available if all bytes in the section are available.
+  //
+  // Interface Version: 1
+  // Implementation Required: Yes
+  //
+  //   pThis  - pointer to the interface structure.
+  //   offset - the offset of the data section in the file.
+  //   size   - the size of the data section.
+  //
+  // Returns true if the specified data section at |offset| of |size|
+  // is available.
   FPDF_BOOL (*IsDataAvail)(struct _FX_FILEAVAIL* pThis,
                            size_t offset,
                            size_t size);
 } FX_FILEAVAIL;
-
 typedef void* FPDF_AVAIL;
 
-/**
-* Function: FPDFAvail_Create
-*           Create a document availability provider.
-*
-* Parameters:
-*           file_avail  -   Pointer to file availability interface to check
-* availability of file data.
-*           file        -   Pointer to a file access interface for reading data
-* from file.
-* Return value:
-*           A handle to the document availability provider. NULL for error.
-* Comments:
-*           Application must call FPDFAvail_Destroy when done with the
-* availability provider.
-*/
+// Create a document availability provider.

[Tom Sepez, 2016/03/23 20:10:58]

nit: wish we could say what an availabilty provider represents or does.

[dsinclair, 2016/03/23 23:35:58]

Yea, will have to come back to that one. My understanding is pretty shaky on
what it actually does. Will flush it out once I've played with it some.

+//
+//   file_avail - pointer to file availability interface.
+//   file       - pointer to a file access interface.
+//
+// Returns a handle to the document availability provider. NULL otherwise.

[Tom Sepez, 2016/03/23 20:10:58]

nit: I prefer ", or NULL on error." to otherwise.  I think its more precise. 
"Otherwise on tuesday ... "

[dsinclair, 2016/03/23 23:35:59]

Done.

+//
+// |FPDFAvail_Destroy| must be called when done with the availability provider.
 DLLEXPORT FPDF_AVAIL STDCALL FPDFAvail_Create(FX_FILEAVAIL* file_avail,
                                               FPDF_FILEACCESS* file);
 
-/**
-* Function: FPDFAvail_Destroy
-*           Destroy a document availibity provider.
-*
-* Parameters:
-*           avail       -   Handle to document availability provider returned by
-* FPDFAvail_Create
-* Return Value:
-*           None.
-*/
+// Destroy the |avail| document availability provider.
+//
+// |avail| - handle to document availability provider to be destroyed.
 DLLEXPORT void STDCALL FPDFAvail_Destroy(FPDF_AVAIL avail);
 
-/**
- * Interface: FX_DOWNLOADHINTS
- *          Download hints interface. Used to receive hints for further
- * downloading.
- */
+// Download hints interface. Used to receive hints for further downloading.
 typedef struct _FX_DOWNLOADHINTS {
-  /**
-   * Version number of the interface. Currently must be 1.
-   */
+  // Version number of the interface. Must be 1.
   int version;
 
-  /**
-   * Method: AddSegment
-   *      Add a section to be downloaded.
-   * Interface Version:
-   *      1
-   * Implementation Required:
-   *      Yes
-   * Parameters:
-   *      pThis       -   Pointer to the interface structure itself.
-   *      offset      -   The offset of the hint reported to be downloaded.
-   *      size        -   The size of the hint reported to be downloaded.
-   * Return Value:
-   *      None.
-   * Comments:
-   *      Called by Foxit SDK to report some downloading hints for download
-   * manager.
-   *      The position and size of section may be not accurate, part of the
-   * section might be already available.
-   *      The download manager must deal with that to maximize download
-   * efficiency.
-   */
+  // Add a section to be downloaded.
+  //
+  // Interface Version: 1
+  // Implementation Required: Yes
+  //
+  //   pThis  - pointer to the interface structure.
+  //   offset - the offset of the hint reported to be downloaded.
+  //   size   - the size of the hint reported to be downloaded.
+  //
+  // The |offset| and |size| of the section may not be unique. Part of the
+  // section might be already available. The download manager must deal with
+  // duplicate sections.

[Tom Sepez, 2016/03/23 20:10:58]

nit: overlapping sections.

[dsinclair, 2016/03/23 23:35:58]

Done.

   void (*AddSegment)(struct _FX_DOWNLOADHINTS* pThis,
                      size_t offset,
                      size_t size);
 } FX_DOWNLOADHINTS;
 
-/**
-* Function: FPDFAvail_IsDocAvail
-*           Check whether the document is ready for loading, if not, get
-* download hints.
-*
-* Parameters:
-*           avail       -   Handle to document availability provider returned by
-* FPDFAvail_Create
-*           hints       -   Pointer to a download hints interface, receiving
-* generated hints
-* Return value:
-*           PDF_DATA_ERROR: A common error is returned. It can't tell
-*                           whehter data are availabe or not.
-*           PDF_DATA_NOTAVAIL: Data are not yet available.
-*           PDF_DATA_AVAIL: Data are available.
-* Comments:
-*           Applications should call this function whenever new data arrived,
-*           and process all the generated download hints if any, until the
-*           function returns PDF_DATA_ERROR or PDF_DATA_AVAIL. Then
-*           applications can call FPDFAvail_GetDocument() to get a document
-*           handle.
-*/
+// Checks if the document is ready for loading, if not, get download hints.
+//
+//   avail - handle to document availability provider.
+//   hints - pointer to a download hints interface.
+//
+// Returns one of:
+//   PDF_DATA_ERROR: A common error is returned. Data availability unknown.
+//   PDF_DATA_NOTAVAIL: Data not yet available.
+//   PDF_DATA_AVAIL: Data available.
+//
+// Applications should call this function whenever new data arrives, and process
+// all the generated download hints, if any, until the function returns
+// |PDF_DATA_ERROR| or |PDF_DATA_AVAIL|.
+//
+// Once all data is available, call |FPDFAvail_GetDocument| to get a document
+// handle.
 DLLEXPORT int STDCALL
 FPDFAvail_IsDocAvail(FPDF_AVAIL avail, FX_DOWNLOADHINTS* hints);
 
-/**
-* Function: FPDFAvail_GetDocument
-*           Get document from the availability provider.
-*
-* Parameters:
-*           avail       -   Handle to document availability provider returned by
-* FPDFAvail_Create
-*     password  -   Optional password for decrypting the PDF file.
-* Return value:
-*           Handle to the document.
-* Comments:
-*           After FPDFAvail_IsDocAvail() returns TRUE, the application should
-* call this function to
-*           get the document handle. To close the document, use
-* FPDF_CloseDocument function.
-*/
+// Get document from the availability provider.
+//
+//   avail    - handle to document availability provider.
+//   password - password for decrypting the PDF file. Optional.
+//
+// Returns a handle to the document.
+//
+// When |FPDFAvail_IsDocAvail| returns TRUE, call |FPDFAvail_GetDocument| to
+// retrieve the document handle.
 DLLEXPORT FPDF_DOCUMENT STDCALL FPDFAvail_GetDocument(FPDF_AVAIL avail,
                                                       FPDF_BYTESTRING password);
 
-/**
-* Function: FPDFAvail_GetFirstPageNum
-*           Get page number for the first available page in a linearized PDF
-*
-* Parameters:
-*           doc         -   A document handle returned by FPDFAvail_GetDocument
-* Return Value:
-*           Zero-based index for the first available page.
-* Comments:
-*           For most linearized PDFs, the first available page would be just the
-* first page, however,
-*           some PDFs might make other page to be the first available page.
-*           For non-linearized PDF, this function will always return zero.
-*/
+// Get the page number for the first available page in a linearized PDF.
+//
+//   doc - document handle.
+//
+// Returns the zero-based index for the first available page.
+//
+// For most linearized PDFs, the first available page will be the first page,
+// however, some PDFs might make another page the first available page.
+// For non-linearized PDFs, this function will always return zero.
 DLLEXPORT int STDCALL FPDFAvail_GetFirstPageNum(FPDF_DOCUMENT doc);
 
-/**
-* Function: FPDFAvail_IsPageAvail
-*           Check whether a page is ready for loading, if not, get download
-* hints.
-*
-* Parameters:
-*           avail       -   Handle to document availability provider returned by
-* FPDFAvail_Create
-*           page_index  -   Index number of the page. 0 for the first page.
-*           hints       -   Pointer to a download hints interface, receiving
-* generated hints
-* Return value:
-*           PDF_DATA_ERROR: A common error is returned. It can't tell
-*                           whehter data are availabe or not.
-*           PDF_DATA_NOTAVAIL: Data are not yet available.
-*           PDF_DATA_AVAIL: Data are available.
-* Comments:
-*           This function can be called only after FPDFAvail_GetDocument is
-*           called. Applications should call this function whenever new data
-*           arrived and process all the generated download hints if any, until
-*           this function returns PDF_DATA_ERROR or PDF_DATA_AVAIL. Then
-*           applications can perform page loading.
-*/
+// Check if |page_index| is ready for loading, if not, get the
+// |FX_DOWNLOADHINTS|.
+//
+//   avail      - handle to document availability provider.
+//   page_index - index number of the page. Zero for the first page.
+//   hints      - pointer to a download hints interface. Populated if
+//                |page_index| is not available.
+//
+// Returns one of:
+//   PDF_DATA_ERROR: A common error is returned. Data availability unknown.
+//   PDF_DATA_NOTAVAIL: Data not yet available.
+//   PDF_DATA_AVAIL: Data available.
+//
+// This function can be called only after |FPDFAvail_GetDocument| is called.
+// Applications should call this function whenever new data arrives and process
+// all the generated download |hints|, if any, until this function returns
+// |PDF_DATA_ERROR| or |PDF_DATA_AVAIL|. Applications can then perform page
+// loading.
 DLLEXPORT int STDCALL FPDFAvail_IsPageAvail(FPDF_AVAIL avail,
                                             int page_index,
                                             FX_DOWNLOADHINTS* hints);
 
-/**
-* Function: FPDFAvail_ISFormAvail
-*           Check whether Form data is ready for init, if not, get download
-* hints.
-*
-* Parameters:
-*           avail       -   Handle to document availability provider returned by
-* FPDFAvail_Create
-*           hints       -   Pointer to a download hints interface, receiving
-* generated hints
-* Return value:
-*           PDF_FORM_ERROR    - A common eror, in general incorrect parameters,
-*                               like 'hints' is nullptr.
-*           PDF_FORM_NOTAVAIL - data not available
-*           PDF_FORM_AVAIL    - data available
-*           PDF_FORM_NOTEXIST - no form data
-* Comments:
-*           This function can be called only after FPDFAvail_GetDocument is
-*           called.
-*           The application should call this function whenever new data arrived,
-* and process all the
-*           generated download hints if any, until the function returns non-zero
-* value. Then the
-*           application can perform page loading. Recommend to call
-* FPDFDOC_InitFormFillEnvironment
-*           after the function returns non-zero value.
-*/
+// Check if form data is ready for initialization, if not, get the
+// |FX_DOWNLOADHINTS|.
+//
+//   avail - handle to document availability provider.
+//   hints - pointer to a download hints interface. Populated if form is not
+//           ready for initialization.
+//
+// Returns one of:
+//   PDF_FORM_ERROR: A common eror, in general incorrect parameters.
+//   PDF_FORM_NOTAVAIL: Data not available.
+//   PDF_FORM_AVAIL: Data available.
+//   PDF_FORM_NOTEXIST: No form data.
+//
+// This function can be called only after |FPDFAvail_GetDocument| is called.
+// The application should call this function whenever new data arrives and
+// process all the generated download |hints|, if any, until the function
+// |PDF_FORM_ERROR|, |PDF_FORM_AVAIL| or |PDF_FORM_NOTEXIST|.
+// Applications can then perform page loading. It is recommend to call
+// |FPDFDOC_InitFormFillEnvironment| when |PDF_FORM_AVAIL| is returned.
 DLLEXPORT int STDCALL FPDFAvail_IsFormAvail(FPDF_AVAIL avail,
                                             FX_DOWNLOADHINTS* hints);
 
-/**
-* Function: FPDFAvail_IsLinearized
-*           To check whether a document is Linearized PDF file.
-*
-* Parameters:
-*           avail       -   Handle to document availability provider returned by
-* FPDFAvail_Create
-* Return value:
-*           PDF_LINEARIZED is a linearize file.
-*           PDF_NOT_LINEARIZED is not a linearize file.
-*           PDF_LINEARIZATION_UNKNOWN doesn't know whether the file is a
-*linearize file.
-*
-* Comments:
-*           It return PDF_LINEARIZED or PDF_NOT_LINEARIZED as soon as
-*           we have first 1K data.  If the file's size less than 1K, it returns
-*           PDF_LINEARIZATION_UNKNOWN because there is not enough information to
-*           tell whether a PDF file is a linearized file or not.
-*
-*/
+// Check whether a document is a linearized PDF.
+//
+//   avail - handle to document availability provider.
+//
+// Returns one of:
+//   PDF_LINEARIZED
+//   PDF_NOT_LINEARIZED
+//   PDF_LINEARIZATION_UNKNOWN
+//
+// |FPDFAvail_IsLinearized| will return |PDF_LINEARIZED| or |PDF_NOT_LINEARIZED|
+// when we have 1k  of data. If the files size less than 1k, it returns
+// |PDF_LINEARIZATION_UNKNOWN| as there is insufficient information to determine
+// if the PDF is linearlized.
 DLLEXPORT int STDCALL FPDFAvail_IsLinearized(FPDF_AVAIL avail);
 
 #ifdef __cplusplus
-}
-#endif
+}  // extern "C"
+#endif  // __cplusplus
 
 #endif  // PUBLIC_FPDF_DATAAVAIL_H_