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 94904)
+++ ppapi/cpp/url_response_info.h	(working copy)
@@ -9,42 +9,109 @@
 #include "ppapi/cpp/resource.h"
 #include "ppapi/cpp/var.h"
 
+/// @file
+/// This file defines the API for examining URL responses.
 namespace pp {
 
 class FileRef;
 
+/// 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 <code>is_null</code>

[polina, 2011/08/03 00:28:33]

same comment about consistency as in the other file

[jond, 2011/08/05 17:07:47]

Right. I will address these all at the same time across all files.

On 2011/08/03 00:28:33, polina wrote:

+  /// 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.
+  /// A special structure used by the constructor that does not increment the
+  /// reference count of the underlying resource.
   struct PassRef {};
+
+  /// A constructor used when you have received a <code>PP_Resource</code> as a
+  /// return value that has already been reference counted.
+  ///
+  /// @param[in] resource A <code>PP_Resource</code>.
   URLResponseInfo(PassRef, PP_Resource resource);
 
+  /// The copy constructor.

[polina, 2011/08/03 00:28:33]

for <code>URLResponseInfo</code>?

[jond, 2011/08/05 17:07:47]

Done.

[jond, 2011/08/05 17:07:47]

Done.

   URLResponseInfo(const URLResponseInfo& other);
 
-  // PPB_URLResponseInfo methods:
+  /// This function gets a response property.
+  ///
+  /// @param[in] property A <code>PP_URLResponseProperty</code> identifying the
+  /// type of property in the response.
+  /// @return A <code>Var</code> containing the response property value if
+  /// successful, <code>is_undefined Var</code> if an input parameter is
+  /// invalid.
   Var GetProperty(PP_URLResponseProperty property) const;
-  FileRef GetBodyAsFileRef() const;
 
-  // Convenient helpers for getting properties:
+  /// This function returns a <code>FileRef</code>
+  /// pointing to the file containing the response body.  This
+  /// is only valid if <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set
+  /// on the <code>URLRequestInfo</code> used to produce this response.  This
+  /// file remains valid until the <code>URLLoader</code> associated with this
+  /// <code>URLResponseInfo is closed or destroyed.
+  ///
+  /// @return A <code>FileRef_Dev</code> corresponding to a

[polina, 2011/08/03 00:28:33]

no _Dev here and in the function signature?
(sync issue?)

[polina, 2011/08/04 22:01:04]

Still erroneous _Dev in your comment.

[jond, 2011/08/05 17:07:47]

Done.

+  /// <code>FileRef</code> if successful, an <code>is_null</code> object if
+  /// <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was not requested or if
+  /// the <code>URLLoader</code> has not been opened yet.
+  FileRef_Dev GetBodyAsFileRef() const;
+
+  /// This function gets the <code>PP_URLRESPONSEPROPERTY_URL</code>
+  /// property for the response.
+  ///
+  /// @return An <code>is_string Var</code> containing the response property
+  /// value if successful, <code>is_undefined Var</code> if an input parameter
+  /// is invalid.
   Var GetURL() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_URL);
   }
+
+  /// This function gets the <code>PP_URLRESPONSEPROPERTY_REDIRECTURL</code>
+  /// property for the response.
+  ///
+  /// @return An <code>is_string Var</code> containing the response property
+  /// value if successful, <code>is_undefined Var</code> if an input parameter
+  /// is invalid.
   Var GetRedirectURL() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_REDIRECTURL);
   }
+
+  /// This function gets the <code>PP_URLRESPONSEPROPERTY_REDIRECTMETHOD</code>
+  /// property for the response.
+  ///
+  /// @return An <code>is_string Var</code> containing the response property
+  /// value if successful, <code>is_undefined Var</code> if an input parameter
+  /// is invalid.
   Var GetRedirectMethod() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_REDIRECTMETHOD);
   }
+
+  /// This function gets the <code>PP_URLRESPONSEPROPERTY_STATUSCODE</code>
+  /// property for the response.
+  ///
+  /// @return A int32_t containing the response property value if successful,
+  /// <code>is_undefined Var</code> if an input parameter is invalid.
   int32_t GetStatusCode() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_STATUSCODE).AsInt();
   }
+
+  /// This function gets the <code>PP_URLRESPONSEPROPERTY_STATUSLINE</code>
+  /// property for the response.
+  ///
+  /// @return An <code>is_string Var</code> containing the response property
+  /// value if successful, <code>is_undefined Var</code> if an input parameter
+  /// is invalid.
   Var GetStatusLine() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_STATUSLINE);
   }
+
+  /// This function gets the <code>PP_URLRESPONSEPROPERTY_HEADERS</code>
+  /// property for the response.
+  ///
+  /// @return An <code>is_string Var</code> containing the response property
+  /// value if successful, <code>is_undefined Var</code> if an input parameter
+  /// is invalid.
   Var GetHeaders() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_HEADERS);
   }