C++ documentation for URL Loading classes

ppapi/cpp/url_response_info.h

Index: ppapi/cpp/url_response_info.h
===================================================================
--- ppapi/cpp/url_response_info.h	(revision 91508)
+++ ppapi/cpp/url_response_info.h	(working copy)
@@ -9,42 +9,103 @@
 #include "ppapi/cpp/resource.h"
 #include "ppapi/cpp/var.h"
 
+/// @file
+/// This file defines the API for examining URL responses.
 namespace pp {
 
 class FileRef_Dev;
 
+/// URLResponseInfo provides an API for examaning URL responses.
 class URLResponseInfo : public Resource {
  public:
-  // Creates an is_null() URLResponseInfo object.
+  // Default constructor. This constructor creates an is_null resource.
   URLResponseInfo() {}
 
-  // This constructor is used when we've gotten a PP_Resource as a return value
-  // that has already been addref'ed for us.
+  /// Not sure what to put here

[polina, 2011/08/01 10:35:51]

Copy from image_data.h

[jond, 2011/08/01 21:03:09]

Done.

   struct PassRef {};
+
+  /// A constructor used when a PP_Resource is provided as a return value

[polina, 2011/08/01 10:35:51]

not really
Copy from image_data.h

[jond, 2011/08/01 21:03:09]

Done.

+  /// whose reference count has already been incremented.
+  ///
+  /// @param[in] resource A PP_Resource.
   URLResponseInfo(PassRef, PP_Resource resource);
 
+  /// A constructor for copying an URLResponseInfo.

[polina, 2011/08/01 10:35:51]

The copy constructor

[jond, 2011/08/01 21:03:09]

Done.

   URLResponseInfo(const URLResponseInfo& other);
 
   // PPB_URLResponseInfo methods:

[polina, 2011/08/01 10:35:51]

Did you leave this here by accident?

[jond, 2011/08/01 21:03:09]

Done.

+
+  /// This function gets a response property.
+  ///
+  /// @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,

[polina, 2011/08/01 10:35:51]

Var, not PP_Var
(please apply to other functions as well)

[jond, 2011/08/01 21:03:09]

Done.

+  /// PP_VARTYPE_VOID if an input parameter is invalid.

[polina, 2011/08/01 10:35:51]

is_undefined Var, not PP_VARTYPE_VOID
(please apply to other functions as well)

[jond, 2011/08/01 21:03:09]

Done.

[jond, 2011/08/01 21:03:09]

Done.

   Var GetProperty(PP_URLResponseProperty property) const;
+
+  /// This function returns a FileRef

[polina, 2011/08/01 10:35:51]

You seem to be using <code> in some places, but not others. Is that on purpose?
Is there some kind of pattern I am not recognizing?

[jond, 2011/08/01 21:03:09]

Done.

+  /// 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.
+  ///
+  /// @return A PP_Resource corresponding to a FileRef if successful, 0 if

[polina, 2011/08/01 10:35:51]

FileRef_Dev, not PP_Resource

[polina, 2011/08/01 10:35:51]

is_null object, not 0

[jond, 2011/08/01 21:03:09]

Done.

[jond, 2011/08/01 21:03:09]

Done.

[jond, 2011/08/01 21:03:09]

Done.

+  /// PP_URLREQUESTPROPERTY_STREAMTOFILE was not requested or if the URLLoader
+  /// has not been opened yet.
   FileRef_Dev GetBodyAsFileRef() const;
 
-  // Convenient helpers for getting properties:
+  /// This function gets the PP_URLRESPONSEPROPERTY_URL (corresponding to a

[polina, 2011/08/01 10:35:51]

instead of putting "corresponding to a type..." in (), I would put it in the
description of the return value:

@return An is_string Var ...., is_undefined Var ....

(for all other functions too)

[jond, 2011/08/01 21:03:09]

Done.

+  /// string of type PP_VARTYPE_STRING) property for the response.
+  ///
+  /// @return A PP_Var containing the response property value if successful,
+  /// PP_VARTYPE_VOID if an input parameter is invalid.
   Var GetURL() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_URL);
   }
+
+  /// This function gets the PP_URLRESPONSEPROPERTY_REDIRECTURL (corresponding
+  /// to a string of type PP_VARTYPE_STRING) property for the response.
+  ///
+  /// @return A PP_Var containing the response property value if successful,
+  /// PP_VARTYPE_VOID if an input parameter is invalid.
   Var GetRedirectURL() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_REDIRECTURL);
   }
+
+  /// This function gets the PP_URLRESPONSEPROPERTY_REDIRECTMETHOD
+  /// (corresponding to a string of type PP_VARTYPE_STRING) property for the
+  /// response.
+  ///
+  /// @return A PP_Var containing the response property value if successful,
+  /// PP_VARTYPE_VOID if an input parameter is invalid.
   Var GetRedirectMethod() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_REDIRECTMETHOD);
   }
+
+  /// This function gets the PP_URLRESPONSEPROPERTY_STATUSCODE (corresponding
+  /// to an int32 of type PP_VARTYPE_INT32) property for the response.
+  ///
+  /// @return A int32_t containing the response property value if successful,
+  /// PP_VARTYPE_VOID if an input parameter is invalid.
   int32_t GetStatusCode() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_STATUSCODE).AsInt();
   }
+
+  /// This function gets the PP_URLRESPONSEPROPERTY_STATUSLINE (corresponding
+  /// to a string of type PP_VARTYPE_STRING) property for the response.
+  ///
+  /// @return A PP_Var containing the response property value if successful,
+  /// PP_VARTYPE_VOID if an input parameter is invalid.
   Var GetStatusLine() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_STATUSLINE);
   }
+
+  /// This function gets the PP_URLRESPONSEPROPERTY_HEADERS (corresponding to a
+  /// string of type PP_VARTYPE_STRING) property for the response.
+  ///
+  /// @return A PP_Var containing the response property value if successful,
+  /// PP_VARTYPE_VOID if an input parameter is invalid.
   Var GetHeaders() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_HEADERS);
   }