Added/modified documentation for Doxygen

Review URL: http://codereview.chromium.org/6532065

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@82116 0039d316-1c4b-4281-b951-d872f2087c98

3 files changed, 327 insertions, 129 deletions

diff --git a/ppapi/c/ppb_url_loader.h b/ppapi/c/ppb_url_loader.h
index 34a16da..0d1c288 100644
--- a/ppapi/c/ppb_url_loader.h
+++ b/ppapi/c/ppb_url_loader.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2010 The Chromium Authors. All rights reserved.
+/* Copyright (c) 2011 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
@@ -16,7 +16,7 @@ struct PP_CompletionCallback;
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PPB_URLLoader interface for loading URLs.
  */
 
 /**
@@ -24,95 +24,176 @@ struct PP_CompletionCallback;
  * @{
  */
 
-// The interface for loading URLs.
-//
-// Typical steps for loading an URL:
-// 1- Create an URLLoader object.
-// 2- Create an URLRequestInfo object and set properties on it.
-// 3- Call URLLoader's Open method passing the URLRequestInfo.
-// 4- When Open completes, call GetResponseInfo to examine the response headers.
-// 5- Then call ReadResponseBody to stream the data for the response.
-//
-// Alternatively, if PP_URLREQUESTPROPERTY_STREAMTOFILE was set on the
-// URLRequestInfo, then call FinishStreamingToFile at step #5 to wait for the
-// downloaded file to be complete.  The downloaded file may be accessed via the
-// GetBody method of the URLResponseInfo returned in step #4.
-//
+/**
+ * The PPB_URLLoader interface contains pointers to functions for loading URLs.
+ * The typical steps for loading a URL are:
+ *
+ * -# Call Create() to create a URLLoader object.</li>
+ * -# Create a URLRequestInfo object and set properties on it. Refer to
+ * PPB_URLRequestInfo for further information.</li>
+ * -# Call Open() with the URLRequestInfo as an argument.</li>
+ * -# When Open() completes, call GetResponseInfo() to examine the response
+ * headers. Refer to PPB_URLResponseInfo for further information.</li>
+ * -# Call ReadResponseBody() to stream the data for the response.</li>
+ *
+ * Alternatively, if PP_URLREQUESTPROPERTY_STREAMTOFILE was set on the
+ * URLRequestInfo in step #2:
+ * - Call FinishStreamingToFile(), after examining the response headers
+ * (step #4),  to wait for the downloaded file to be complete.
+ * - Then, access the downloaded file using the GetBodyAsFileRef() function of
+ * the URLResponseInfo returned in step #4.
+ */
 struct PPB_URLLoader {
-  // Create a new URLLoader object.  Returns 0 if the instance is invalid.  The
-  // URLLoader is associated with a particular instance, so that any UI dialogs
-  // that need to be shown to the user can be positioned relative to the window
-  // containing the instance.  It is also important for security reasons to
-  // know the origin of the URL request.
+  /**
+   * Create is a pointer to a function that creates a new URLLoader
+   * object. The URLLoader is associated with a particular instance, so that
+   * any UI dialogs that need to be shown to the user can be positioned
+   * relative to the window containing the instance.
+   *
+   * @param[in] instance A PP_Instance indentifying one instance of a module.
+   * @return A PP_Resource corresponding to a URLLoader if successful, 0 if
+   * the instance is invalid.
+   */
   PP_Resource (*Create)(PP_Instance instance);
 
-  // Returns PP_TRUE if the given resource is an URLLoader. Returns PP_FALSE if
-  // the resource is invalid or some type other than an URLLoader.
+  /**
+   * IsURLLoader is a pointer to a function that determines if a resource is a
+   * URLLoader.
+   *
+   * @param[in] resource A PP_Resource corresponding to a URLLoader.
+   * @return PP_TRUE if the resource is a URLLoader, PP_FALSE if the resource is
+   * invalid or some type other than URLLoader.
+   */
   PP_Bool (*IsURLLoader)(PP_Resource resource);
 
-  // Begins loading the URLRequestInfo.  Completes when response headers are
-  // received or when an error occurs.  Use the GetResponseInfo method to
-  // access the response headers.
+  /**
+   * Open is a pointer to a function that begins loading the URLRequestInfo.
+   * The operation completes when response headers are received or when an
+   * error occurs.  Use GetResponseInfo() to access the response
+   * headers.
+   *
+   * @param[in] loader A PP_Resource corresponding to a URLLoader.
+   * @param[in] resource A PP_Resource corresponding to a URLRequestInfo.
+   * @param[in] callback A PP_CompletionCallback to run on asynchronous
+   * completion of Open(). This callback will run when response
+   * headers for the url are received or error occured. This callback
+   * will only run if Open() returns PP_OK_COMPLETIONPENDING.
+   */
   int32_t (*Open)(PP_Resource loader,
                   PP_Resource request_info,
                   struct PP_CompletionCallback callback);
 
-  // If the current URLResponseInfo object corresponds to a redirect, then call
-  // this method to follow the redirect.
+  /**
+   * FollowRedirect is a pointer to a function that can be invoked to follow a
+   * redirect after Open() completed on receiving redirect headers.
+   *
+   * @param[in] loader A PP_Resource corresponding to a URLLoader.
+   * @param[in] callback A PP_CompletionCallback to run on asynchronous
+   * completion of FollowRedirect(). This callback will run when response
+   * headers for the redirect url are received or error occured. This callback
+   * will only run if FollowRedirect() returns PP_OK_COMPLETIONPENDING.
+   * @return An int32_t containing an error code from pp_errors.h.
+   */
   int32_t (*FollowRedirect)(PP_Resource loader,
                             struct PP_CompletionCallback callback);
 
-  // Returns the current upload progress, which is meaningful after Open has
-  // been called. Progress only refers to the request body and does not include
-  // the headers.
-  //
-  // This data is only available if the URLRequestInfo passed to Open() had the
-  // PP_URLREQUESTPROPERTY_REPORTUPLOADPROGRESS flag set to PP_TRUE.
-  //
-  // This method returns PP_FALSE if upload progress is not available.
+  /**
+   * GetUploadProgress is a pointer to a function that returns the current
+   * upload progress (which is meaningful after Open() has been called).
+   * Progress only refers to the request body and does not include the
+   * headers.
+   *
+   * This data is only available if the URLRequestInfo passed to Open() had the
+   * PP_URLREQUESTPROPERTY_REPORTUPLOADPROGRESS property set to PP_TRUE.
+   *
+   * @param[in] loader A PP_Resource corresponding to a URLLoader.
+   * @param[in] bytes_sent The number of bytes sent thus far.
+   * @parm[in] total_bytes_to_be_sent The total number of bytes to be sent.
+   * @return PP_TRUE if the upload progress is available, PP_FALSE if it is not
+   * available.
+   */
   PP_Bool (*GetUploadProgress)(PP_Resource loader,
                                int64_t* bytes_sent,
                                int64_t* total_bytes_to_be_sent);
 
-  // Returns the current download progress, which is meaningful after Open has
-  // been called.  Progress only refers to the response body and does not
-  // include the headers.
-  //
-  // This data is only available if the URLRequestInfo passed to Open() had the
-  // PP_URLREQUESTPROPERTY_REPORTDOWNLOADPROGRESS flag set to PP_TRUE.
-  //
-  // The total bytes to be received may be unknown, in which case
-  // total_bytes_to_be_received will be set to -1. This method returns PP_FALSE
-  // if download progress is not available.
+  /**
+   * GetDownloadProgress is a pointer to a function that returns the current
+   * download progress, which is meaningful after Open() has been called.
+   * Progress only refers to the response body and does not include the
+   * headers.
+   *
+   * This data is only available if the URLRequestInfo passed to Open() had the
+   * PP_URLREQUESTPROPERTY_REPORTDOWNLOADPROGRESS property set to PP_TRUE.
+   *
+   * @param[in] loader A PP_Resource corresponding to a URLLoader.
+   * @param[in] bytes_received The number of bytes received thus far.
+   * @parm[in] total_bytes_to_be_received The total number of bytes to be
+   * received. The total bytes to be received may be unknown, in which case
+   * total_bytes_to_be_received will be set to -1.
+   * @return PP_TRUE if the download progress is available, PP_FALSE if it is
+   * not available.
+   */
   PP_Bool (*GetDownloadProgress)(PP_Resource loader,
                                  int64_t* bytes_received,
                                  int64_t* total_bytes_to_be_received);
 
-  // Returns the current URLResponseInfo object.
+  /**
+   * GetResponseInfo is a pointer to a function that returns the current
+   * URLResponseInfo object.
+   *
+   * @param[in] instance A PP_Resource corresponding to a URLLoader.
+   * @return A PP_Resource corresponding to the URLResponseInfo if successful,
+   * 0 if the loader is not a valid resource or if Open() has not been called.
+   */
   PP_Resource (*GetResponseInfo)(PP_Resource loader);
 
-  // Call this method to read the response body.  The size of the buffer must
-  // be large enough to hold the specified number of bytes to read.  May
-  // perform a partial read.  Returns the number of bytes read or an error
-  // code.
+  /**
+   * ReadResponseBody is a pointer to a function used to read the response
+   * body. The size of the buffer must be large enough to hold the specified
+   * number of bytes to read.  This function might perform a partial read.
+   *
+   * @param[in] loader A PP_Resource corresponding to a URLLoader.
+   * @param[in/out] buffer A pointer to the buffer for the response body.
+   * @param[in] bytes_to_read The number of bytes to read.
+   * @param[in] callback A PP_CompletionCallback to run on asynchronous
+   * completion. The callback will run if the bytes (full or partial) are
+   * read or an error occurs asynchronously. This callback will run only if this
+   * function returns PP_OK_COMPLETIONPENDING.
+   * @return An int32_t containing the number of bytes read or an error code
+   * from pp_errors.h.
+   */
   int32_t (*ReadResponseBody)(PP_Resource loader,
                               void* buffer,
                               int32_t bytes_to_read,
                               struct PP_CompletionCallback callback);
-
-  // If PP_URLREQUESTPROPERTY_STREAMTOFILE was set on the URLRequestInfo passed
-  // to the Open method, then this method may be used to wait for the response
-  // body to be completely downloaded to the file provided by URLResponseInfo's
-  // GetBody method.
+  /**
+   * FinishStreamingToFile is a pointer to a function used to wait for the
+   * response body to be completely downloaded to the file provided by the
+   * GetBodyAsFileRef() in the current URLResponseInfo. This function is only
+   * used if PP_URLREQUESTPROPERTY_STREAMTOFILE was set on the URLRequestInfo
+   * passed to Open().
+   *
+   * @param[in] loader A PP_Resource corresponding to a URLLoader.
+   * @param[in] callback A PP_CompletionCallback to run on asynchronous
+   * completion. This callback will run when body is downloaded or an error
+   * occurs after FinishStreamingToFile() returns PP_OK_COMPLETIONPENDING.
+   * @return An int32_t containing the number of bytes read or an error code
+   * from pp_errors.h.
+   */
   int32_t (*FinishStreamingToFile)(PP_Resource loader,
                                    struct PP_CompletionCallback callback);
 
-  // Cancels any IO that may be pending, and closes the URLLoader object.  Any
-  // pending callbacks will still run, reporting PP_ERROR_ABORTED if pending IO
-  // was interrupted.  It is NOT valid to call Open again after a call to this
-  // method.  Note: If the URLLoader object is destroyed, and it is still open,
-  // then it will be implicitly closed, so you are not required to call the
-  // Close method.
+  /**
+   * Close is a pointer to a function used to cancel any pending IO and close
+   * the URLLoader object. Any pending callbacks will still run, reporting
+   * PP_ERROR_ABORTED if pending IO was interrupted.  It is NOT valid to call
+   * Open() again after a call to this function.
+   *
+   * Note: If the URLLoader object is destroyed while it is still open, then it
+   * will be implicitly closed so you are not required to call Close().
+   *
+   * @param[in] loader A PP_Resource corresponding to a URLLoader.
+   */
   void (*Close)(PP_Resource loader);
 };
 /**
diff --git a/ppapi/c/ppb_url_request_info.h b/ppapi/c/ppb_url_request_info.h
index 259760e..6c6e516 100644
--- a/ppapi/c/ppb_url_request_info.h
+++ b/ppapi/c/ppb_url_request_info.h
@@ -16,31 +16,66 @@ struct PP_Var;
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PPB_URLRequestInfo API for creating and manipulating
+ * URL requests. This API is used in conjunction with PPB_URLLoader.
  */
 
 /**
- *
  * @addtogroup Enums
  * @{
  */
+
+/**
+ * This enumeration contains properties that can be set on a URL request.
+ */
 typedef enum {
-  PP_URLREQUESTPROPERTY_URL,                  // string
-  PP_URLREQUESTPROPERTY_METHOD,               // string
-  PP_URLREQUESTPROPERTY_HEADERS,              // string, \n-delim
-  PP_URLREQUESTPROPERTY_STREAMTOFILE,         // PP_Bool (default=PP_FALSE)
-  PP_URLREQUESTPROPERTY_FOLLOWREDIRECTS,      // PP_Bool (default=PP_TRUE)
-
-  // Set to true if you want to be able to poll the download progress via the
-  // URLLoader.GetDownloadProgress function.
-  //
-  // Boolean (default = PP_FALSE).
+  /** This corresponds to a string (PP_VARTYPE_STRING). */
+  PP_URLREQUESTPROPERTY_URL,
+
+  /**
+   * This corresponds to a string (PP_VARTYPE_STRING); either POST or GET.
+   * Refer to the
+   * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html">HTTP
+   * Methods</a> documentation for further information.
+   *
+   */
+  PP_URLREQUESTPROPERTY_METHOD,
+
+  /**
+   * This corresponds to a string (PP_VARTYPE_STRING); \n delimited.
+   * Refer to the
+   * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html"Header
+   * Field Definitions</a> documentaiton for further information.
+   */
+  PP_URLREQUESTPROPERTY_HEADERS,
+
+  /**
+   * This corresponds to a PP_Bool (PP_VARTYPE_BOOL; default=PP_FALSE).
+   * Set this value to PP_TRUE if you want to download the data to a file. Use
+   * PPB_URLLoader.FinishStreamingToFile() to complete the download.
+   */
+  PP_URLREQUESTPROPERTY_STREAMTOFILE,
+
+  /**
+   * This corresponds to a PP_Bool (PP_VARTYPE_BOOL; default=PP_TRUE).
+   * Set this value to PP_FALSE if you want to use
+   * PPB_URLLoader.FollowRedirects() to follow the redirects only after
+   * examining redirect headers.
+   */
+  PP_URLREQUESTPROPERTY_FOLLOWREDIRECTS,
+
+  /**
+   * This corresponds to a PP_Bool (PP_VARTYPE_BOOL; default=PP_FALSE).
+   * Set this value to PP_TRUE if you want to be able to poll the download
+   * progress using PPB_URLLoader.GetDownloadProgress().
+   */
   PP_URLREQUESTPROPERTY_RECORDDOWNLOADPROGRESS,
 
-  // Set to true if you want to be able to poll the upload progress via the
-  // URLLoader.GetUploadProgress function.
-  //
-  // Boolean (default = PP_FALSE).
+  /**
+   * This corresponds to a PP_Bool (default=PP_FALSE).
+   * Set this value to PP_TRUE if you want to be able to poll the upload
+   * progress using PPB_URLLoader.GetUplaodProgress().
+   */
   PP_URLREQUESTPROPERTY_RECORDUPLOADPROGRESS,
 
   // Set to a String to set a custom referrer (if empty, the referrer header
@@ -80,46 +115,87 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_URLRequestProperty, 4);
  * @addtogroup Interfaces
  * @{
  */
+
+/**
+ * The PPB_URLRequestInfo interface contains pointers to functions for creating
+ * and handling URL requests. Refer to PPB_URLLoader for further information.
+ */
 struct PPB_URLRequestInfo {
-  // Create a new URLRequestInfo object.  Returns 0 if the module is invalid.
+  /**
+   * Create is a pointer to a function that creates a new URLRequestInfo
+   * object.
+   *
+   * @param[in] instance A PP_Instance indentifying one instance of a module.
+   * @return A PP_Resource identifying the URLRequestInfo if successful, 0 if
+   * the instance is invalid.
+   */
   PP_Resource (*Create)(PP_Instance instance);
 
-  // Returns PP_TRUE if the given resource is an URLRequestInfo. Returns
-  // PP_FALSE if the resource is invalid or some type other than an
-  // URLRequestInfo.
+  /**
+   * IsURLRequestInfo is a pointer to a function that determines if a resource
+   * is a URLRequestInfo.
+   *
+   * @param[in] resource A PP_Resource corresponding to a URLRequestInfo.
+   * @return PP_TRUE if the resource is a URLRequestInfo,
+   * PP_FALSE if the resource is invalid or some type other than
+   * URLRequestInfo.
+   */
   PP_Bool (*IsURLRequestInfo)(PP_Resource resource);
 
-  // Sets a request property.  Returns PP_FALSE if any of the parameters are
-  // invalid, PP_TRUE on success.  The value property must be the correct type
-  // according to the property being set.
+  /**
+   * SetProperty is a pointer to a function that sets a request property. The
+   * value of the property must be the correct type according to the property
+   * being set.
+   *
+   * @param[in] request A PP_Resource corresponding to a URLRequestInfo.
+   * @param[in] property A PP_URLRequestProperty identifying the
+   * property to set.
+   * @param[in] value A PP_Var containing the property value.
+   * @return PP_TRUE if successful, PP_FALSE if any of the
+   * parameters are invalid.
+   */
   PP_Bool (*SetProperty)(PP_Resource request,
                          PP_URLRequestProperty property,
                          struct PP_Var value);
 
-  // Append data to the request body.
-  //
-  // A Content-Length request header will be automatically generated.
-  //
-  // Returns PP_FALSE if any of the parameters are invalid, PP_TRUE on success.
+  /**
+   * AppendDataToBody is a pointer to a function that appends data to the
+   * request body. A Content-Length request header will be automatically
+   * generated.
+   *
+   * @param[in] request A PP_Resource corresponding to a URLRequestInfo.
+   * @param[in] data A pointer to a buffer holding the data.
+   * @param[in] len The length, in bytes, of the data.
+   * @return PP_TRUE if successful, PP_FALSE if any of the
+   * parameters are invalid.
+   *
+   *
+   */
   PP_Bool (*AppendDataToBody)(PP_Resource request,
                               const void* data,
                               uint32_t len);
 
-  // Append a file reference to be uploaded.
-  //
-  // A sub-range of the file starting from start_offset may be specified.  If
-  // number_of_bytes is -1, then the sub-range to upload extends to the end of
-  // the file.
-  //
-  // An optional (non-zero) last modified time stamp may be provided, which
-  // will be used to validate that the file was not modified since the given
-  // time before it is uploaded.  The upload will fail with an error code of
-  // PP_Error_FileChanged if the file has been modified since the given time.
-  // If expected_last_modified_time is 0, then no validation is performed.
-  //
-  // A Content-Length request header will be automatically generated.
-  //
-  // Returns PP_FALSE if any of the parameters are invalid, PP_TRUE on success.
+  /**
+   * AppendFileToBody is a pointer to a function used to append a file, to be
+   * uploaded, to the request body. A content-length request header will be
+   * automatically generated.
+   *
+   * @param[in] request A PP_Resource corresponding to a URLRequestInfo.
+   * @param[in] file_ref A PP_Resource containing the file reference.
+   * @param[in] start_offset An optional starting point offset within the
+   * file.
+   * @param[in] number_of_bytes An optional number of bytes of the file to
+   * be included. If number_of_bytes is -1, then the sub-range to upload
+   * extends to the end of the file.
+   * @param[in] expected_last_modified_time An optional (non-zero) last
+   * modified time stamp used to validate that the file was not modified since
+   * the given time before it was uploaded. The upload will fail with an error
+   * code of PP_ERROR_FILECHANGED if the file has been modified since the given
+   * time. If expected_last_modified_time is 0, then no validation is
+   * performed.
+   * @return PP_TRUE if successful, PP_FALSE if any of the
+   * parameters are invalid.
+   */
   PP_Bool (*AppendFileToBody)(PP_Resource request,
                               PP_Resource file_ref,
                               int64_t start_offset,
diff --git a/ppapi/c/ppb_url_response_info.h b/ppapi/c/ppb_url_response_info.h
index cd918e8..51c62af 100644
--- a/ppapi/c/ppb_url_response_info.h
+++ b/ppapi/c/ppb_url_response_info.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2010 The Chromium Authors. All rights reserved.
+/* Copyright (c) 2011 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
@@ -12,7 +12,8 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PPB_URLResponseInfo API for examining URL
+ * responses.
  */
 
 /**
@@ -20,13 +21,31 @@
  * @addtogroup Enums
  * @{
  */
+
+/**
+ * This enumeration contains properties set on a URL response.
+ */
+// TODO(viettrungluu) Explain each property in more detail (e.g. note how the
+// full URL in the response corresponds to the relative URL in the original
+// request).
 typedef enum {
-  PP_URLRESPONSEPROPERTY_URL,             // string
-  PP_URLRESPONSEPROPERTY_REDIRECTURL,     // string
-  PP_URLRESPONSEPROPERTY_REDIRECTMETHOD,  // string
-  PP_URLRESPONSEPROPERTY_STATUSCODE,      // int32
-  PP_URLRESPONSEPROPERTY_STATUSLINE,      // string
-  PP_URLRESPONSEPROPERTY_HEADERS          // string, \n-delim
+  /** This corresponds to a string (PP_VARTYPE_STRING). */
+  PP_URLRESPONSEPROPERTY_URL,
+
+  /** This corresponds to a string (PP_VARTYPE_STRING).*/
+  PP_URLRESPONSEPROPERTY_REDIRECTURL,
+
+  /** This corresponds to a string (PP_VARTYPE_STRING).*/
+  PP_URLRESPONSEPROPERTY_REDIRECTMETHOD,
+
+  /** This corresponds to an int32 (PP_VARETYPE_INT32)*/
+  PP_URLRESPONSEPROPERTY_STATUSCODE,
+
+  /** This corresponds to a string (PP_VARTYPE_STRING).*/
+  PP_URLRESPONSEPROPERTY_STATUSLINE,
+
+  /** This corresponds to a string(PP_VARTYPE_STRING), \n delimited */
+  PP_URLRESPONSEPROPERTY_HEADERS
 } PP_URLResponseProperty;
 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_URLResponseProperty, 4);
 /**
@@ -36,32 +55,54 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_URLResponseProperty, 4);
 #define PPB_URLRESPONSEINFO_INTERFACE "PPB_URLResponseInfo;0.1"
 
 /**
- * @file
- * Defines the API ...
- */
-
-/**
  *
  * @addtogroup Interfaces
  * @{
  */
+
+/**
+ * The PPB_URLResponseInfo interface contains pointers to functions for
+ * examining URL responses. Refer to PPB_URLLoader for further
+ * information.
+ */
 struct PPB_URLResponseInfo {
-  // Returns PP_TRUE if the given resource is an URLResponseInfo. Returns
-  // PP_FALSE if the resource is invalid or some type other than an
-  // URLResponseInfo.
+
+  /**
+   * IsURLResponseInfo is a pointer to a function that determines if a
+   * response is a URLResponseInfo.
+   *
+   * @param[in] resource A PP_Resource corresponding to a URLResponseInfo.
+   * @return PP_TRUE if the resource is a URLResponseInfo,
+   * PP_FALSE if the resource is invalid or some type other than
+   * URLResponseInfo.
+   */
   PP_Bool (*IsURLResponseInfo)(PP_Resource resource);
 
-  // Gets a response property.  Return PP_VarType_Void if an input parameter is
-  // invalid.
+  /**
+   * GetProperty is a pointer to a function that gets a response property.
+   *
+   * @param[in] request A PP_Resource corresponding to a URLResponseInfo.
+   * @param[in] property A PP_URLResponseProperty identifying the type of
+   * property in the response.
+   * @return A PP_Var containing the response property value if successful,
+   * PP_VARTYPE_VOID if an input parameter is invalid.
+   */
   struct PP_Var (*GetProperty)(PP_Resource response,
                                PP_URLResponseProperty property);
 
-  // Returns a FileRef pointing to the file containing the response body.  This
-  // is only valid if PP_URLREQUESTPROPERTY_STREAMTOFILE was set on the
-  // URLRequestInfo used to produce this response.  This file remains valid
-  // until the URLLoader associated with this URLResponseInfo is closed or
-  // destroyed.  Returns 0 if PP_URLREQUESTPROPERTY_STREAMTOFILE was not
-  // requested or if the URLLoader has not been opened yet.
+  /**
+   * GetBodyAsFileRef is a pointer to a function that returns a FileRef
+   * pointing to the file containing the response body.  This
+   * is only valid if PP_URLREQUESTPROPERTY_STREAMTOFILE was set on the
+   * URLRequestInfo used to produce this response.  This file remains valid
+   * until the URLLoader associated with this URLResponseInfo is closed or
+   * destroyed.
+   *
+   * @param[in] request A PP_Resource corresponding to a URLResponseInfo.
+   * @return A PP_Resource corresponding to a FileRef if successful, 0 if
+   * PP_URLREQUESTPROPERTY_STREAMTOFILE was not requested or if the URLLoader
+   * has not been opened yet.
+   */
   PP_Resource (*GetBodyAsFileRef)(PP_Resource response);
 };
 /**