Fix small inaccuracies in the HID API documentation.

Fix typos related to which functions send or receive data. Some of these
were already resolved in 1816af67d3fb992ff49fb22b2b8fc8908d6ee6b1. Also
document where the opaque device ID and connection IDs should be used
and how errors are reported.

BUG=392036

Review URL: https://codereview.chromium.org/518133004

Cr-Commit-Position: refs/heads/master@{#292745}

extensions/common/api/hid.idl

@@ -5,6 +5,10 @@
 // Use the <code>chrome.hid</code> API to interact with connected HID devices.
 // This API provides access to HID operations from within the context of an app.
 // Using this API, apps can function as drivers for hardware devices.
+//
+// Errors generated by this API are reported by setting
+// $(ref:runtime.lastError) and executing the function's regular callback. The
+// callback's regular parameters will be undefined in this case.
 namespace hid {
   dictionary HidCollectionInfo {
     // HID usage page identifier.
@@ -16,7 +20,7 @@ namespace hid {
   };
 
   [noinline_doc] dictionary HidDeviceInfo {
-    // Device opaque ID.
+    // Opaque device ID.
     long deviceId;
     // Vendor ID.
     long vendorId;
@@ -32,9 +36,8 @@ namespace hid {
     long maxFeatureReportSize;
   };
 
-  // Returned by <code>connect</code> to represent a communication session with
-  // an HID device. Must be closed with a call to <code>disconnect</code>.
   dictionary HidConnectInfo {
+    // The opaque ID used to identify this connection in all other functions.
     long connectionId;
   };
 
@@ -63,7 +66,7 @@ namespace hid {
   callback ConnectCallback = void (HidConnectInfo connection);
   callback DisconnectCallback = void ();
 
-  // |reportId|: The ID of the report.
+  // |reportId|: The report ID or <code>0</code> if none.
   // |data|: The content of the report.
   callback ReceiveCallback = void (long reportId, ArrayBuffer data);
 
@@ -79,29 +82,23 @@ namespace hid {
                            GetDevicesCallback callback);
 
     // Open a connection to an HID device for communication.
-    // |deviceId|: The ID of the device to open.
+    // |deviceId|: The $(ref:HidDeviceInfo.deviceId) of the device to open.
     static void connect(long deviceId,
                         ConnectCallback callback);
 
     // Disconnect from a device. Invoking operations on a device after calling
     // this is safe but has no effect.
-    // |connectionId|: The connection to close.
+    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
     static void disconnect(long connectionId,
                            optional DisconnectCallback callback);
 
-    // Receive an Input report from an HID device.
-    //
-    // Input reports are returned to the host through the INTERRUPT IN endpoint.
-    // |connectionId|: The connection from which to receive a report.
+    // Receive the next input report from the device.
+    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
     static void receive(long connectionId,
                         ReceiveCallback callback);
 
-    // Send an Output report to an HID device.
-    // <code>send</code> will send the data on the first OUT endpoint, if one
-    // exists. If one does not exist, the report will be sent through the
-    // Control endpoint.
-    //
-    // |connectionId|: The connection to which to send a report.
+    // Send an output report to the device.
+    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
     // |reportId|: The report ID to use, or <code>0</code> if none.
     // |data|: The report data.
     static void send(long connectionId,
@@ -109,19 +106,15 @@ namespace hid {
                      ArrayBuffer data,
                      SendCallback callback);
 
-    // Receive a Feature report from the device.
-    //
-    // |connectionId|: The connection to read Input report from.
-    // |reportId|: The report ID, or zero if none.
+    // Request a feature report from the device.
+    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
+    // |reportId|: The report ID, or <code>0</code> if none.
     static void receiveFeatureReport(long connectionId,
                                      long reportId,
                                      ReceiveFeatureReportCallback callback);
 
-    // Send a Feature report to the device.
-    //
-    // Feature reports are sent over the Control endpoint as a Set_Report
-    // transfer.
-    // |connectionId|: The connection to read Input report from.
+    // Send a feature report to the device.
+    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
     // |reportId|: The report ID to use, or <code>0</code> if none.
     // |data|: The report data.
     static void sendFeatureReport(long connectionId,