Updated comments for gcdPrivate API.

chrome/common/extensions/api/gcd_private.idl

 // Copyright 2014 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.
 
 // Use the <code>chrome.gcdPrivate</code> API to discover GCD APIs and register
 // them.
 namespace gcdPrivate {
 
   enum SetupType { mdns, wifi, cloud };
 
@@ skipping 31 matching lines @@
 
     // Could not connect to the device.
     connectionError,
 
     // Error in establishing session.
     sessionError,
 
     // 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 {
     pinCode,
     embeddedCode
   };
 
   callback CloudDeviceListCallback = void(GCDDevice[] devices);
 
   // |commandDefinitions| : Is "commandDefs" value of device described at
   // https://developers.google.com/cloud-devices/v1/reference/devices
   // TODO(vitalybuka): consider to describe object in IDL.
   callback CommandDefinitionsCallback = void(object commandDefinitions);
 
   // |command| : Described at
   // https://developers.google.com/cloud-devices/v1/reference/commands
   // TODO(vitalybuka): consider to describe object in IDL.
   callback CommandCallback = void(object command);
 
   // |commands| : Array of commands described at
   // https://developers.google.com/cloud-devices/v1/reference/commands
   // TODO(vitalybuka): consider to describe object in IDL.
   callback CommandListCallback = void(object[] commands);
 
   // Generic callback for session calls, with status only.
   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 {
     // Returns the list of cloud devices visible locally or available in the
     // cloud for user account.
     static void getCloudDeviceList(CloudDeviceListCallback callback);
 
     // Queries network for local devices. Triggers an onDeviceStateChanged and
     // onDeviceRemoved events. Call this function *only* after registering for
     // onDeviceStateChanged and onDeviceRemoved events, or it will do nothing.
     static void queryForNewLocalDevices();
 
     // Cache the WiFi password in the browser process for use during
     // 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.
     // |deviceId| : The device to get command definitions for.
     // |callback| : The result callback.
     static void getCommandDefinitions(DOMString deviceId,
                                       CommandDefinitionsCallback callback);
 
     // Creates and sends a new command.
     // |deviceId| : The device to send the command to.
@@ skipping 35 matching lines @@
     // Subscribe to this event to start listening new or updated devices. New
     // listeners will get called with all known devices on the network, and
     // status updates for devices available through the cloud.
     static void onDeviceStateChanged(GCDDevice device);
 
     // Notifies that device has disappeared.
     // |deviceId| : The device has disappeared.
     static void onDeviceRemoved(DOMString deviceId);
   };
 };