Updated comments for gcdPrivate API.

chrome/common/extensions/api/gcd_private.idl

Index: chrome/common/extensions/api/gcd_private.idl
diff --git a/chrome/common/extensions/api/gcd_private.idl b/chrome/common/extensions/api/gcd_private.idl
index dd5c0c8a6b3790498d6cbbd1291fb52bdb6681d4..29f5bef5aec33ed788ff9e8208b3d126797eef96 100644
--- a/chrome/common/extensions/api/gcd_private.idl
+++ b/chrome/common/extensions/api/gcd_private.idl
@@ -49,11 +49,11 @@ namespace gcdPrivate {
     // Unknown session.
     unknownSessionError,
 
-    // Bad pairing code. Ask user to retype.
+    // Bad pairing code.
     badPairingCodeError,
 
-    // Setup error.
-    setupError
+    // Device error with details in response object.
+    deviceError
   };
 
   enum PairingType {
@@ -82,26 +82,26 @@ namespace gcdPrivate {
   callback SessionCallback = void(Status status);
 
   // Called when device starts to establish a secure session.
-  // If |status| is |success| app should vall |startPairing|.
-  // |sessionId| is the session ID (identifies the session for future calls).
-  // |status| is the status (success or type of error).
+  // If |status| is |success| app should call |startPairing|.
+  // |sessionId| : The session ID (identifies the session for future calls).
+  // |status| : The status of operation (success or type of error).
   // |pairingTypes| is the list of supported pairing types.
   callback EstablishSessionCallback = void(long sessionId,
                                            Status status,
                                            PairingType[] pairingTypes);
 
   // Called when the response to the message sent is available or on error.
-  // |status| is the status (success or type of error)
-  // |response| is the response object or null on error
-  callback SendMessageCallback = void(Status status,
-                                      object response);
+  // |status| : The status of operation (success or type of error).
+  // |response| : The response object with result or error description. May be
+  // empty for some errors.
+  callback SendMessageCallback = void(Status status, object response);
 
   // Called as a response to |prefetchWifiPassword|
-  // |success| Denotes whether the password fetch has succeeded or failed.
+  // |success| : Denotes whether the password fetch has succeeded or failed.
   callback SuccessCallback = void(boolean success);
 
   // Called as a response to |getPrefetchedWifiNameList|
-  // |list| the list of ssids for which wifi passwords were prefetched.
+  // |networks| : The list of ssids for which wifi passwords were prefetched.
   callback SSIDListCallback = void(DOMString[] networks);
 
   interface Functions {
@@ -118,40 +118,51 @@ namespace gcdPrivate {
     // provisioning. This is done to allow the gathering of the wifi password to
     // not be done while connected to the device's network. Callback is called
     // with true if wifi password was cached and false if it was unavailable.
+    // |ssid| : The network to prefetch password for.
     static void prefetchWifiPassword(DOMString ssid, SuccessCallback callback);
 
     // Get the list of ssids with prefetched callbacks.
     static void getPrefetchedWifiNameList(SSIDListCallback callback);
 
     // Establish the session.
+    // |ipAddress| : The IPv4 or IPv6 address of the device.
+    // |port| : The port with Privet HTTP server.
     static void establishSession(DOMString ipAddress,
                                  long port,
                                  EstablishSessionCallback callback);
 
-    // Start pairing with selected method.
-    // |pairingType| is the any value provided 
+    // Start pairing with selected method. Should be called after
+    // |establishSession|.
+    // |sessionId| : The ID of the session created with |establishSession|.
+    // |pairingType| : The value selected from the list provided in
+    // callback of |establishSession|.
     static void startPairing(long sessionId,
                              PairingType pairingType,
                              SessionCallback callback);
 
-    // Confirm pairing code.
-    // |code| is the string generated by pairing process and availible to the
+    // Confirm pairing code. Should be called after |startPairing|.
+    // |sessionId| : The ID of the session created with |establishSession|.
+    // |code| : The string generated by pairing process and availible to the
     // user.
     static void confirmCode(long sessionId,
                             DOMString code,
                             SessionCallback callback);
 
-    // Send an encrypted message to the device. |api| is the API path and
-    // |input| is the input object. If the message is a setup message with a
-    // wifi ssid specified but no password, the password cached from
-    // |prefetchWifiPassword| will be used and the call will fail if it's not
-    // available. For open networks use an empty string as the password.
+    // Send an encrypted message to the device.
+    // If the message is a setup message with a wifi ssid specified but no
+    // password, the password cached by |prefetchWifiPassword| will be used and
+    // the call will fail if it's not available. For open networks use an empty
+    // string as the password.
+    // |sessionId| : The ID of the session created with |establishSession|.
+    // |api| : The Privet API name to call.
+    // |input| : Input data for |api|.
     static void sendMessage(long sessionId,
                             DOMString api,
                             object input,
                             SendMessageCallback callback);
 
     // Terminate the session with the device.
+    // |sessionId| : The ID of the session created with |establishSession|.
     static void terminateSession(long sessionId);
 
     // Returns command definitions.