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
+  // available if all bytes in the section are available.
+  //
+  // Interface Version: 1
+  // Implementation Required: Yes
+  //
+  // |pThis|  - pointer to the interface structure.

[Tom Sepez, 2016/03/22 15:51:35]

nit: I don't think we need the vertical bars in a table like this, only when
|pThis| appears as part of a sentence.

[dsinclair, 2016/03/22 16:02:50]

Ack.

+  // |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.
+//
+// |file_avail| - pointer to file availability interface.
+// |file|       - pointer to a file access interface
+//
+// Returns a handle to the document availability provider. NULL otherwise.
+//
+// |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.

[Tom Sepez, 2016/03/22 15:51:34]

I like the "as returned by" part, which clearly indicates how the two functions
are related.

[dsinclair, 2016/03/22 16:02:50]

So, my problem with 'as returned by' is that, what happens if/when we add a
second method that can return FPDFAvail_Create. Do we update all the comments,
leave them outdated? It seems like higher level documentation which should be
tying the two methods together instead of the header docs.

 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.
   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.
+//
+// Return value:
+//  * PDF_DATA_ERROR: A common error is returned. Data availability unknown.

[Tom Sepez, 2016/03/22 15:51:35]

nit: not sure why there's a * here.

[dsinclair, 2016/03/22 16:02:50]

Attempting to show a list, * is a markdown list marker. Anything better I could
use for list representation?

+//  * 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
@@ skipping 102 matching lines @@
 *           tell whether a PDF file is a linearized file or not.
 *
 */
 DLLEXPORT int STDCALL FPDFAvail_IsLinearized(FPDF_AVAIL avail);
 
 #ifdef __cplusplus
 }
 #endif
 
 #endif  // PUBLIC_FPDF_DATAAVAIL_H_