Fix small inaccuracies in the HID API documentation.

extensions/common/api/hid.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.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.
     long usagePage;
     // Page-defined usage identifier.
     long usage;
     // Report IDs which belong to the collection and to its children.
     long[] reportIds;
   };
 
   [noinline_doc] dictionary HidDeviceInfo {
-    // Device opaque ID.
+    // Opaque device ID.
     long deviceId;
     // Vendor ID.
     long vendorId;
     // Product ID.
     long productId;
     // Top-level collections from this device's report descriptors.
     HidCollectionInfo[] collections;
     // Top-level collection's maximum input report size.
     long maxInputReportSize;
     // Top-level collection's maximum output report size.
     long maxOutputReportSize;
     // Top-level collection's maximum feature report size.
     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;
   };
 
   [noinline_doc] dictionary DeviceFilter {
     // Device vendor ID.
     long? vendorId;
     // Device product ID, only checked only if the vendor ID matches.
     long? productId;
     // HID usage page identifier.
     long? usagePage;
     // HID usage identifier, checked only if the HID usage page matches.
     long? usage;
   };
 
   dictionary GetDevicesOptions {
     [deprecated="Equivalent to setting $(ref:DeviceFilter.vendorId)."]
     long? vendorId;
     [deprecated="Equivalent to setting $(ref:DeviceFilter.productId)."]
     long? productId;
     // A device matching any given filter will be returned. An empty filter list
     // will return all devices the app has permission for.
     DeviceFilter[]? filters;
   };
 
   callback GetDevicesCallback = void (HidDeviceInfo[] devices);
   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);
 
   // |data|: The content of the report.
   callback ReceiveFeatureReportCallback = void (ArrayBuffer data);
 
   callback SendCallback = void();
 
   interface Functions {
     // Enumerate connected HID devices.
     // |options|: The properties to search for on target devices.
     static void getDevices(GetDevicesOptions options,
                            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,
                      long reportId,
                      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,
                                   long reportId,
                                   ArrayBuffer data,
                                   SendCallback callback);
   };
 };