Chromium Code Reviews
|
|
Chromium Code Reviews
Issue
23549014:
Update USB API docs (Closed)
|
Created:
7 years, 3 months ago by Bei Zhang Modified:
7 years, 3 months ago CC:
chromium-reviews, chromium-apps-reviews_chromium.org, extensions-reviews_chromium.org Base URL:
https://chromium.googlesource.com/chromium/src.git@master Visibility:
Public. |
DescriptionUpdate USB API docs.
BUG=277139
Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=224046
Patch Set 1 #
Total comments: 98
Patch Set 2 : Fixes #
Total comments: 51
Patch Set 3 : Fixes #
Total comments: 8
Patch Set 4 : Fixes #Messages
Total messages: 12 (0 generated)
Hi Zel, Please review. Thanks, Bei https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... File chrome/common/extensions/docs/templates/articles/app_hardware.html (right): https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:132: Not every device can be opened successfully. Devices that are claimed by the OS cannot be opened in Chrome in general. Zel@, This is the key part to explain interfaceId.
Hi Mike, Please review. Thanks, Bei
I'd like to take another look at this after Andy does a pass for style. The content is more or less OK.
Hi Bei, thanks for updating this article. I took a thorough editing pass through the document. There are many comments, but most of them are quick fixes. Where possible, I tried to explain the reason for specific changes, to help you understand common issues that make documents hard to read and understand. If you have any questions, please ask me. I would be happy to sit down with you and discuss this document in detail. Andy https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... File chrome/common/extensions/docs/templates/articles/app_hardware.html (right): https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:24: You can use the USB API to communicate with USB devices using only JavaScript Replace the first sentence with: """ The <a href="usb.html">USB API</a> lets your app communicate with USB devices using only JavaScript code. """ https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:25: code. Some devices are not accessible through this API - see the <a Replace the part after the dash with: """ See <a href="#caveats">Caveats</a> below for details. """ https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:29: <p> Delete this paragraph -- it does not fit into the introduction. (We'll include this information later.) https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:35: <p> The anchor text "here" is not helpful, especially for people who scan this document quickly. Replace this paragraph with: """ For background information about USB, see the official <a href="http://www.usb.org/home">USB specifications</a>, as well as this reasonable <a href="http://www.beyondlogic.org/usbnutshell/usb1.shtml">crash course</a>. """ https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:44: <p>The USB API requires a special permission "usb" in the manifest file:</p> 'a special permission "usb"' -> 'the "usb" permission' https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:52: <p>In order to prevent finger-printing, you must declare all the device type 1) What is fingerprinting? It may be worth adding a parenthetical to explain what this is. 2) You must declare all the specific devices you want to access, not just "device types", right? 3) This sentence is incomplete. You can probably just delete ", other wi" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:53: you want to access in the manifest file, other wi. For each product id/vendor Let's add the information about VID/PID before the sentence that starts with "For". I would write is as follows: """ Each USB device corresponds to a vendor id/product id (VID/PID) pair. You can use $ref:chrome.usb.getDevices to enumerate devices by their VID/PID pair. """ Question: Is there a way to get the VID/PID pair for a device from a list somewhere? Otherwise there seems to be a chicken-or-egg problem here: You have to declare VID/PID pairs in the manifest before you can use chrome.usb, but you need to use chrome.usb.getDevices to get the VID/PID pairs. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:54: id pair of the device, you need to declare it in manifest file under Replace the sentence that starts with "For" with: """ You must declare the VID/PID pair for each device you want to use under the "usbDevices" permission in your app's manifest file, as shown in the example below: """ https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:68: <i>Note that only decimal numbers are allowed in JSON format. You cannot pass 1) Replace the <i> tag with <p class="note">. It's better to use fewer fonts. 2) Replace the second sentence with: """ You cannot use hexadecimal numbers in these fields. """ https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:74: To find a device, use the $ref:chrome.usb.getDevices "Find" implies that you can search for and discover devices, which I don't think you can do. I would replace "To find a device" with: """ To determine whether one or more specific devices are connected to a user's system """ https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:75: method which has two parameters: Delete "which has two parameters:". https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:91: <td>An object specifying both a <code>vendorId</code> (long) and <code>productId</code> Can you only specify one object (device) at a time? The fact that you get an array of objects in the callback would imply that you can specify multiple devices as input for getDevices(), no? https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:100: <td>Called when the device scan is finished. The callback will be I would replace "scan" with "search" or maybe "identification". To me, scan implies discovering devices, which I don't think you can do. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:102: three properties: <code>device</code>, <code>vendorId</code>, <code>productId</code>. How is the "device" property used? https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:103: If no devices could be found, the array will be empty. "could be found" -> "are found" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:127: <h3 id="usb_open">Opening the device</h3> "the" -> "a" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:128: Once the <code>Device</code> objects are returned you can open the device using 1) Wrap your text in a <p> tag. 2) Add a comma after "returned". 3) "the device" -> "a device" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:130: communicate with the device using this handle. "the device" -> "devices" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:132: Not every device can be opened successfully. Devices that are claimed by the OS cannot be opened in Chrome in general. Start a new paragraph with "Not". I would start this paragraph as follows: """ <p class="note"> Not every device can be opened successfully. In general, devices that are claimed by the OS cannot be opened in Chrome. On Linux (other than Chrome OS), once one device interface is claimed by the OS, the whole device is locked down, even if other interfaces of the device can be used. """ https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:134: if the other interfaces of the device can be used. On Chrome OS, it is possible to request access to these devices using It's not clear what "these devices" refers to. Maybe use: "such devices". https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:137: To simplify the opending process, you can call $ref:chrome.usb.findDevices 1) I would start a new paragraph with "To simplify...". 2) "opending" -> "opening" 3) "call" -> "use the" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:138: method which enumerates, requests access and opens the devices in one call. 1) Add a comma after "method" 2) Add a comma after "access" 3) It would be helpful to provide a sample call for openDevice(), and a table that describes the parameters, like for other methods in this article. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:143: USB protocol defines four types of transfers: <a href="#control_transfers">control</a>, "USB" -> "The USB" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:145: and <a href="#interrupt_transfers">interrupt</a>. Theoretically they can occur Delete the sentence that starts with "Theorectically...", and add the following sentence: """ These transfers are described below. """ https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:151: However, due to the nature of the USB protocol, both inbound and outbound messages must be initiated by the host (your computer). For inbound (device-to-host) messages, the host, your JavaScript code, sends a message flagged as "inbound" to the device. The exact contents of the message depends on the device, but usually will have some identification of what you are requesting from it. The device then responds with the requested data. The device's response is handled by Chrome and delivered asynchronously to the callback you specified in the transfer method. 1) Start this paragraph with: """ Transfers can occur in both directions: device-to-host (inbound), and host-to-device (outbound). Due to the nature... """ 2) "your computer" -> "the user's computer" 3) Replace the following commas with parentheses: ", your JavaScript code," -> "(your JavaScript Code)" 4) "exact contents" -> "exact content" 5) "you specified" -> "you specify" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:175: <td>Contains the data sent by the device if transfer was inbound.</td> "transfer" -> "the transfer" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:188: chrome.usb.bulkTransfer(device, transferInfo, onTransferCallback); "device" -> "connectionHandle" ? https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:194: command parameters to a USB device. It always sends to endpoint 0 and no 1) It's not clear what "It" refers to. Maybe: "The controlTransfer method always..."? 2) Add a comma after "0". https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:211: <td>Object sent in $ref:chrome.usb.openDevice callback. "sent" -> "received" ? https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:217: device protocol specification for specifics. "specifics" -> "details" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:247: <td>"in" or "out". "in" direction is used to notify the device that it Start the second sentence with: """ The "in" direction is used """ https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:248: should send information to the host. All communication in a USB bus is "in" -> "on" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:289: "data": new Uint8Array([4, 8, 15, 16, 23, 42]).buffer // Note that the ArrayBuffer, not the TypedArray it self is used. 1) "it self" -> "itself" 2) I don't understand this comment. Can you please clarify? https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:296: <p>Isochronous transfers is the most complex type of USB transfers. They are "is" -> "are" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:298: isochronous transfer (either inbound or outbound), you must use:</p> "you must use" -> "you must use the isochronousTransfer() method:" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:313: <td>Object sent in $ref:chrome.usb.openDevice callback. "sent" -> "received" ? https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:390: back. USB devices don't send transfers to the bus unless the host explicitly "the bus" -> "the USB bus" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:396: <p>Bulk transfer is an USB transfer type commonly used to transfer a large Start this paragraph with: """ Bulk transfers are commonly used to... """ https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:397: amount of data in a reliable way. The method has three parameters:</p> "The method" -> "The bulkTransfer() method" When you say "the method", it has to be clear which method you're talking about. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:412: <td>Object sent in $ref:chrome.usb.openDevice callback. "sent" -> "received" ? https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:470: <p>Interrupt transfers are used to send important notifications. Since all An example of an "important notification" would be helpful. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:473: data back if there is anything in the interrupt queue. The method has three "The method" -> "The interruptTransfer() method" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:499: doesn't contain the device's response. It's just to notify your code that "It's just" -> "The purpose of the callback is simply" https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:500: the asynchronous transfer request has been processed and you can go ahead. Go ahead with what? Maybe end the sentence after "processed". https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:553: default. To access it through this API, your user will need to have write What does "it" refer to? Try: "To access devices through this API..." https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:554: access too. A simple solution is to set a udev rule. Create a file Do users need to set this rule? Or can an app do that? If users need to set the rule, we should tell developers that they may want to provide instructions in their app telling end-users what they need to do. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:564: Then, just restart the udev daemon: <code>service udev restart</code>. You can Replace the last sentence with: """ You can check if device permissions are set correctly by following these steps: """ https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:569: <li>Find the bus and device numbers in <code>lsusb</code></li> Replace the first step with: """ Run <code>lsusb</code> to find the bus and device numbers. """ https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:570: <li><code>ls -al /dev/bus/usb/[bus]/[device]</code>. This file should be owned Start the second step with: """ Run <code>ls... """ When you have a list of items, it's much easier to read/process the list if the items all use a parallel structure.
Great job, Andy! Thanks A LOT! I also want to know if there is way I can debug it in a real docs page (with all the scaffoldings)? https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... File chrome/common/extensions/docs/templates/articles/app_hardware.html (right): https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:24: You can use the USB API to communicate with USB devices using only JavaScript On 2013/09/05 22:51:36, Andy wrote: > Replace the first sentence with: > > """ > The <a href="usb.html">USB API</a> lets your app communicate with USB devices > using only JavaScript code. > """ Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:25: code. Some devices are not accessible through this API - see the <a On 2013/09/05 22:51:36, Andy wrote: > Replace the part after the dash with: > > """ > See <a href="#caveats">Caveats</a> below for details. > """ Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:29: <p> On 2013/09/05 22:51:36, Andy wrote: > Delete this paragraph -- it does not fit into the introduction. (We'll include > this information later.) Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:35: <p> On 2013/09/05 22:51:36, Andy wrote: > The anchor text "here" is not helpful, especially for people who scan this > document quickly. Replace this paragraph with: > > """ > For background information about USB, see the official > <a href="http://www.usb.org/home">USB specifications</a>, > as well as this reasonable > <a href="http://www.beyondlogic.org/usbnutshell/usb1.shtml">crash course</a>. > """ Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:44: <p>The USB API requires a special permission "usb" in the manifest file:</p> On 2013/09/05 22:51:36, Andy wrote: > 'a special permission "usb"' -> 'the "usb" permission' Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:52: <p>In order to prevent finger-printing, you must declare all the device type On 2013/09/05 22:51:36, Andy wrote: > 1) What is fingerprinting? It may be worth adding a parenthetical to explain > what this is. > > 2) You must declare all the specific devices you want to access, not just > "device types", right? PID is the id of the device type. > > 3) This sentence is incomplete. You can probably just delete ", other wi" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:53: you want to access in the manifest file, other wi. For each product id/vendor On 2013/09/05 22:51:36, Andy wrote: > Let's add the information about VID/PID before the sentence that starts with > "For". I would write is as follows: > > """ > Each USB device corresponds to a vendor id/product id (VID/PID) pair. You can > use $ref:chrome.usb.getDevices to enumerate devices by their VID/PID pair. > """ > > Question: Is there a way to get the VID/PID pair for a device from a list > somewhere? Otherwise there seems to be a chicken-or-egg problem here: You have > to declare VID/PID pairs in the manifest before you can use chrome.usb, but you > need to use chrome.usb.getDevices to get the VID/PID pairs. The VIDs are approved by http://www.usb.org/developers/vendor/. PID is rather vendor specific. There is an official registry we are using to resolve the name of the devices, but it is far from complete. This pid/vid list is imported at src/third_party/usb_ids/usb.ids. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:54: id pair of the device, you need to declare it in manifest file under On 2013/09/05 22:51:36, Andy wrote: > Replace the sentence that starts with "For" with: > > """ > You must declare the VID/PID pair for each device you want to use under the > "usbDevices" permission in your app's manifest file, > as shown in the example below: > """ Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:68: <i>Note that only decimal numbers are allowed in JSON format. You cannot pass On 2013/09/05 22:51:36, Andy wrote: > 1) Replace the <i> tag with <p class="note">. It's better to use fewer fonts. > > 2) Replace the second sentence with: > > """ > You cannot use hexadecimal numbers in these fields. > """ Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:74: To find a device, use the $ref:chrome.usb.getDevices On 2013/09/05 22:51:36, Andy wrote: > "Find" implies that you can search for and discover devices, which I don't think > you can do. I would replace "To find a device" with: > > """ > To determine whether one or more specific devices are connected to a user's > system > """ Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:75: method which has two parameters: On 2013/09/05 22:51:36, Andy wrote: > Delete "which has two parameters:". Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:91: <td>An object specifying both a <code>vendorId</code> (long) and <code>productId</code> On 2013/09/05 22:51:36, Andy wrote: > Can you only specify one object (device) at a time? The fact that you get an > array of objects in the callback would imply that you can specify multiple > devices as input for getDevices(), no? As explained above, VID/PID refers to a type of devices, not a specific one. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:100: <td>Called when the device scan is finished. The callback will be On 2013/09/05 22:51:36, Andy wrote: > I would replace "scan" with "search" or maybe "identification". To me, scan > implies discovering devices, which I don't think you can do. Done. I understand why it was called "scan". It's actually enumerate on each bus and slot on the buses. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:102: three properties: <code>device</code>, <code>vendorId</code>, <code>productId</code>. On 2013/09/05 22:51:36, Andy wrote: > How is the "device" property used? Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:103: If no devices could be found, the array will be empty. On 2013/09/05 22:51:36, Andy wrote: > "could be found" -> "are found" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:127: <h3 id="usb_open">Opening the device</h3> On 2013/09/05 22:51:36, Andy wrote: > "the" -> "a" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:128: Once the <code>Device</code> objects are returned you can open the device using On 2013/09/05 22:51:36, Andy wrote: > 1) Wrap your text in a <p> tag. > > 2) Add a comma after "returned". > > 3) "the device" -> "a device" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:130: communicate with the device using this handle. On 2013/09/05 22:51:36, Andy wrote: > "the device" -> "devices" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:132: Not every device can be opened successfully. Devices that are claimed by the OS cannot be opened in Chrome in general. On 2013/09/05 22:51:36, Andy wrote: > Start a new paragraph with "Not". I would start this paragraph as follows: > > """ > <p class="note"> > Not every device can be opened successfully. > In general, devices that are claimed by the OS cannot be opened > in Chrome. > On Linux (other than Chrome OS), once one device interface > is claimed by the OS, the whole device is locked down, > even if other interfaces of the device can be used. > """ Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:134: if the other interfaces of the device can be used. On Chrome OS, it is possible to request access to these devices using On 2013/09/05 22:51:36, Andy wrote: > It's not clear what "these devices" refers to. Maybe use: "such devices". Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:137: To simplify the opending process, you can call $ref:chrome.usb.findDevices On 2013/09/05 22:51:36, Andy wrote: > 1) I would start a new paragraph with "To simplify...". > > 2) "opending" -> "opening" > > 3) "call" -> "use the" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:138: method which enumerates, requests access and opens the devices in one call. On 2013/09/05 22:51:36, Andy wrote: > 1) Add a comma after "method" > > 2) Add a comma after "access" > > 3) It would be helpful to provide a sample call for openDevice(), and a table > that describes the parameters, like for other methods in this article. Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:143: USB protocol defines four types of transfers: <a href="#control_transfers">control</a>, On 2013/09/05 22:51:36, Andy wrote: > "USB" -> "The USB" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:145: and <a href="#interrupt_transfers">interrupt</a>. Theoretically they can occur On 2013/09/05 22:51:36, Andy wrote: > Delete the sentence that starts with "Theorectically...", and add the following > sentence: > > """ > These transfers are described below. > """ Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:151: However, due to the nature of the USB protocol, both inbound and outbound messages must be initiated by the host (your computer). For inbound (device-to-host) messages, the host, your JavaScript code, sends a message flagged as "inbound" to the device. The exact contents of the message depends on the device, but usually will have some identification of what you are requesting from it. The device then responds with the requested data. The device's response is handled by Chrome and delivered asynchronously to the callback you specified in the transfer method. On 2013/09/05 22:51:36, Andy wrote: > 1) Start this paragraph with: > > """ > Transfers can occur in both directions: device-to-host (inbound), and > host-to-device (outbound). Due to the nature... > """ > > 2) "your computer" -> "the user's computer" > > 3) Replace the following commas with parentheses: ", your JavaScript code," -> > "(your JavaScript Code)" > > 4) "exact contents" -> "exact content" > > 5) "you specified" -> "you specify" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:175: <td>Contains the data sent by the device if transfer was inbound.</td> On 2013/09/05 22:51:36, Andy wrote: > "transfer" -> "the transfer" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:188: chrome.usb.bulkTransfer(device, transferInfo, onTransferCallback); On 2013/09/05 22:51:36, Andy wrote: > "device" -> "connectionHandle" ? Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:194: command parameters to a USB device. It always sends to endpoint 0 and no On 2013/09/05 22:51:36, Andy wrote: > 1) It's not clear what "It" refers to. Maybe: "The controlTransfer method > always..."? > > 2) Add a comma after "0". Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:211: <td>Object sent in $ref:chrome.usb.openDevice callback. On 2013/09/05 22:51:36, Andy wrote: > "sent" -> "received" ? Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:217: device protocol specification for specifics. On 2013/09/05 22:51:36, Andy wrote: > "specifics" -> "details" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:247: <td>"in" or "out". "in" direction is used to notify the device that it On 2013/09/05 22:51:36, Andy wrote: > Start the second sentence with: > > """ > The "in" direction is used > """ Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:248: should send information to the host. All communication in a USB bus is On 2013/09/05 22:51:36, Andy wrote: > "in" -> "on" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:289: "data": new Uint8Array([4, 8, 15, 16, 23, 42]).buffer // Note that the ArrayBuffer, not the TypedArray it self is used. On 2013/09/05 22:51:36, Andy wrote: > 1) "it self" -> "itself" > > 2) I don't understand this comment. Can you please clarify? Means you cannot pass `new Uint8Array(...)` to it. Instead, you need to pass a `new Uint8Array(...).buffer` to it. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:296: <p>Isochronous transfers is the most complex type of USB transfers. They are On 2013/09/05 22:51:36, Andy wrote: > "is" -> "are" Done. Not sure about this though. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:298: isochronous transfer (either inbound or outbound), you must use:</p> On 2013/09/05 22:51:36, Andy wrote: > "you must use" -> "you must use the isochronousTransfer() method:" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:313: <td>Object sent in $ref:chrome.usb.openDevice callback. On 2013/09/05 22:51:36, Andy wrote: > "sent" -> "received" ? Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:390: back. USB devices don't send transfers to the bus unless the host explicitly On 2013/09/05 22:51:36, Andy wrote: > "the bus" -> "the USB bus" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:396: <p>Bulk transfer is an USB transfer type commonly used to transfer a large On 2013/09/05 22:51:36, Andy wrote: > Start this paragraph with: > > """ > Bulk transfers are commonly used to... > """ Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:397: amount of data in a reliable way. The method has three parameters:</p> On 2013/09/05 22:51:36, Andy wrote: > "The method" -> "The bulkTransfer() method" > > When you say "the method", it has to be clear which method you're talking about. Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:412: <td>Object sent in $ref:chrome.usb.openDevice callback. On 2013/09/05 22:51:36, Andy wrote: > "sent" -> "received" ? Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:473: data back if there is anything in the interrupt queue. The method has three On 2013/09/05 22:51:36, Andy wrote: > "The method" -> "The interruptTransfer() method" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:499: doesn't contain the device's response. It's just to notify your code that On 2013/09/05 22:51:36, Andy wrote: > "It's just" -> "The purpose of the callback is simply" Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:500: the asynchronous transfer request has been processed and you can go ahead. On 2013/09/05 22:51:36, Andy wrote: > Go ahead with what? Maybe end the sentence after "processed". Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:553: default. To access it through this API, your user will need to have write On 2013/09/05 22:51:36, Andy wrote: > What does "it" refer to? Try: "To access devices through this API..." Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:554: access too. A simple solution is to set a udev rule. Create a file On 2013/09/05 22:51:36, Andy wrote: > Do users need to set this rule? Or can an app do that? If users need to set > the rule, we should tell developers that they may want to provide instructions > in their app telling end-users what they need to do. Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:564: Then, just restart the udev daemon: <code>service udev restart</code>. You can On 2013/09/05 22:51:36, Andy wrote: > Replace the last sentence with: > > """ > You can check if device permissions are set correctly by following these steps: > """ Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:569: <li>Find the bus and device numbers in <code>lsusb</code></li> On 2013/09/05 22:51:36, Andy wrote: > Replace the first step with: > > """ > Run <code>lsusb</code> to find the bus and device numbers. > """ Done. https://codereview.chromium.org/23549014/diff/1/chrome/common/extensions/docs... chrome/common/extensions/docs/templates/articles/app_hardware.html:570: <li><code>ls -al /dev/bus/usb/[bus]/[device]</code>. This file should be owned On 2013/09/05 22:51:36, Andy wrote: > Start the second step with: > > """ > Run <code>ls... > """ > > When you have a list of items, it's much easier to read/process the list if the > items all use a parallel structure. Done.
On 2013/09/06 07:37:15, Bei Zhang wrote: > Great job, Andy! Thanks A LOT! > I also want to know if there is way I can debug it in a real docs page (with all > the scaffoldings)? Hi Bei, happy to help. Once you upload a patch, you can see a preview of your document at: https://chrome-apps-doc.appspot.com/_patch/23549014/apps/app_hardware.html (For different CLs, adjust the CL number and the doc name as appropriate.) Thanks for making all the changes. I'll take another quick peek at the document on Friday morning. Andy
Much improved, Bei. I took a pass through the document and added a few more comments inline. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... File chrome/common/extensions/docs/templates/articles/app_hardware.html (right): https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:25: using only JavaScript code. Some devices are not accessible through this API - The convention is to separate asides with a long dash. Replace "-" with either "--" or "–". https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:26: see <a href="#caveats">Caveats</a> below for more details. Delete "more". You haven't provided any details so far, so "more" details is incorrect. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:34: is a reasonable crash course about it (you may be able to finish it within 24 1) Delete the parenthetical "(you may be able... )". Different people learn at different rates. 2) "about it" -> "that you may find helpful" https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:48: <p>In order to prevent Start this paragraph with a transition: "In addition, in order to..." https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:50: you must declare all the device type you want to access in the manifest file. "type" -> "types" (plural) https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:96: the bus. Your manifest must declare the<code>usbDevices</code> permission add a space after the second "the" https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:136: Once the <code>Device</code> objects are returned, you can open it using "it" -> "a device" ("it" does not have a clear antecedent) https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:173: Not every device can be opened successfully. In general, OS locked down many "OS locked" -> "operating systems lock" https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:175: and etc.) and they cannot be claimed by user application. On Linux (other than 1) Delete the first "and" 2) "application" -> "applications" (plural) https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:186: method, which enumerates, requests access, and opens the devices in one call: Delete "the". You're not talking about any specific devices here. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:192: <p>which equivalents to:</p> Replace this line with: "which is equivalent to" https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:233: computer runs the Chrome App). 1) "runs" -> "that runs" 2) "App" -> "app" (lower case "a") https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:236: The detail of the message depends on the device, but usually will have 1) "detail" -> "details" (plural) 2) "depends" -> "depend" https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:286: /reads from endpoint 0, and no claimInterface is required. Delete spaces before "/". https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:340: bus is host-initiated, so use an 'in' transfer to allow a device to<br/> Use double-quotes around "in" for consistency. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:388: <p>Isochronous transfer is the most complex type of USB transfers. They are "USB transfers" -> "USB transfer" (singular) https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:485: <p class="note"> It's awkward to have two "note" paragraphs in a row. Instead, use just one paragraph, and separate the content with <br>s, eg: <p class="note"> content part 1 <br><br> content part 2 </p> https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:494: <p>Bulk transfers are commonly used to transfer a large amount of non-time Use dashes to link all 3 words: "non", "time", and "sensitive", otherwise the reader won't known which words to group together. "non-time-sensitive" https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:569: <p>Interrupt transfers are used to time sensitive, small amount of data. Try this: "... used to transfer small amounts of time-sensitive data." https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:652: default. To open the device through this API, your user will need to have "the" -> "a" (you're not talking about a specific device here) https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:653: write access to them too. "them too" -> "it" https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:676: <p>Your app cannot do this automatically since this needs root access. We "this needs" -> "this procedure requires" https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:678: to <a href="#caveats">this page</a> for reasons.</p> This sentence is not grammatically correct, and the anchor text "this page" is confusing. Try this: """ We recommend that you provide instructions to end-users and link to the <a href="#caveats">Caveats</a> section on this page for an explanation. """ https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:683: <p>Not all devices can be accessed through this API. In general, devices 1) I would move this paragraph to the top of this section (right under the "Caveats" header), since it's of interest to everybody. The Linux stuff is long and should be at the end of the "Caveats" section. 2) "this API" -> "the USB API" https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:686: HID profiles on OSX systems and USB pen drives.</p> Add a comma after "systems".
https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... File chrome/common/extensions/docs/templates/articles/app_hardware.html (right): https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:25: using only JavaScript code. Some devices are not accessible through this API - On 2013/09/06 23:15:01, Andy wrote: > The convention is to separate asides with a long dash. Replace "-" with either > "--" or "–". Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:26: see <a href="#caveats">Caveats</a> below for more details. On 2013/09/06 23:15:01, Andy wrote: > Delete "more". You haven't provided any details so far, so "more" details is > incorrect. Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:34: is a reasonable crash course about it (you may be able to finish it within 24 On 2013/09/06 23:15:01, Andy wrote: > 1) Delete the parenthetical "(you may be able... )". Different people learn at > different rates. > > 2) "about it" -> "that you may find helpful" Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:48: <p>In order to prevent On 2013/09/06 23:15:01, Andy wrote: > Start this paragraph with a transition: "In addition, in order to..." Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:50: you must declare all the device type you want to access in the manifest file. On 2013/09/06 23:15:01, Andy wrote: > "type" -> "types" (plural) Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:96: the bus. Your manifest must declare the<code>usbDevices</code> permission On 2013/09/06 23:15:01, Andy wrote: > add a space after the second "the" Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:136: Once the <code>Device</code> objects are returned, you can open it using On 2013/09/06 23:15:01, Andy wrote: > "it" -> "a device" > ("it" does not have a clear antecedent) Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:173: Not every device can be opened successfully. In general, OS locked down many On 2013/09/06 23:15:01, Andy wrote: > "OS locked" -> "operating systems lock" Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:175: and etc.) and they cannot be claimed by user application. On Linux (other than On 2013/09/06 23:15:01, Andy wrote: > 1) Delete the first "and" > > 2) "application" -> "applications" (plural) Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:186: method, which enumerates, requests access, and opens the devices in one call: On 2013/09/06 23:15:01, Andy wrote: > Delete "the". You're not talking about any specific devices here. Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:192: <p>which equivalents to:</p> On 2013/09/06 23:15:01, Andy wrote: > Replace this line with: "which is equivalent to" Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:233: computer runs the Chrome App). On 2013/09/06 23:15:01, Andy wrote: > 1) "runs" -> "that runs" > > 2) "App" -> "app" (lower case "a") Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:236: The detail of the message depends on the device, but usually will have On 2013/09/06 23:15:01, Andy wrote: > 1) "detail" -> "details" (plural) > > 2) "depends" -> "depend" Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:286: /reads from endpoint 0, and no claimInterface is required. On 2013/09/06 23:15:01, Andy wrote: > Delete spaces before "/". Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:340: bus is host-initiated, so use an 'in' transfer to allow a device to<br/> On 2013/09/06 23:15:01, Andy wrote: > Use double-quotes around "in" for consistency. Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:388: <p>Isochronous transfer is the most complex type of USB transfers. They are On 2013/09/06 23:15:01, Andy wrote: > "USB transfers" -> "USB transfer" (singular) Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:485: <p class="note"> On 2013/09/06 23:15:01, Andy wrote: > It's awkward to have two "note" paragraphs in a row. Instead, use just one > paragraph, and separate the content with <br>s, eg: > > <p class="note"> content part 1 > <br><br> > content part 2 > </p> Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:494: <p>Bulk transfers are commonly used to transfer a large amount of non-time On 2013/09/06 23:15:01, Andy wrote: > Use dashes to link all 3 words: "non", "time", and "sensitive", otherwise the > reader won't known which words to group together. > > "non-time-sensitive" Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:569: <p>Interrupt transfers are used to time sensitive, small amount of data. On 2013/09/06 23:15:01, Andy wrote: > Try this: "... used to transfer small amounts of time-sensitive data." Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:652: default. To open the device through this API, your user will need to have On 2013/09/06 23:15:01, Andy wrote: > "the" -> "a" (you're not talking about a specific device here) Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:653: write access to them too. On 2013/09/06 23:15:01, Andy wrote: > "them too" -> "it" Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:676: <p>Your app cannot do this automatically since this needs root access. We On 2013/09/06 23:15:01, Andy wrote: > "this needs" -> "this procedure requires" Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:678: to <a href="#caveats">this page</a> for reasons.</p> On 2013/09/06 23:15:01, Andy wrote: > This sentence is not grammatically correct, and the anchor text "this page" is > confusing. Try this: > > """ > We recommend that you provide instructions to end-users and link to the <a > href="#caveats">Caveats</a> section on this page for an explanation. > """ Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:683: <p>Not all devices can be accessed through this API. In general, devices On 2013/09/06 23:15:01, Andy wrote: > 1) I would move this paragraph to the top of this section (right under the > "Caveats" header), since it's of interest to everybody. The Linux stuff is long > and should be at the end of the "Caveats" section. > > 2) "this API" -> "the USB API" Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:683: <p>Not all devices can be accessed through this API. In general, devices On 2013/09/06 23:15:01, Andy wrote: > 1) I would move this paragraph to the top of this section (right under the > "Caveats" header), since it's of interest to everybody. The Linux stuff is long > and should be at the end of the "Caveats" section. > > 2) "this API" -> "the USB API" Done. https://codereview.chromium.org/23549014/diff/23001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:686: HID profiles on OSX systems and USB pen drives.</p> On 2013/09/06 23:15:01, Andy wrote: > Add a comma after "systems". Done.
LGTM, with just a few last nits inline. Nice work, Bei. https://codereview.chromium.org/23549014/diff/29001/chrome/common/extensions/... File chrome/common/extensions/docs/templates/articles/app_hardware.html (right): https://codereview.chromium.org/23549014/diff/29001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:173: lock down many types of USB interfaces (e.g. keyboard and mice, mass storage use "keyboards" (plural), to match the other items in the list https://codereview.chromium.org/23549014/diff/29001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:174: devices, WebCams, etc.) and they cannot be claimed by user applications. "WebCams" -> "webcams" (no capitals) https://codereview.chromium.org/23549014/diff/29001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:387: <p>Isochronous transfer is the most complex type of USB transfer. They are I still recommend using plural here: "Isochronous transfers are..." This would match the <h3> header, as well as the first sentence in the sections that describe the other types of transfers. If you stick with singular, I would start the second sentence with "Isochronous transfers are commonly...". https://codereview.chromium.org/23549014/diff/29001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:648: are not accessible either because the Operating System's kernel or a native "either because" -> "because either"
https://codereview.chromium.org/23549014/diff/29001/chrome/common/extensions/... File chrome/common/extensions/docs/templates/articles/app_hardware.html (right): https://codereview.chromium.org/23549014/diff/29001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:173: lock down many types of USB interfaces (e.g. keyboard and mice, mass storage On 2013/09/17 07:06:11, Andy wrote: > use "keyboards" (plural), to match the other items in the list Done. https://codereview.chromium.org/23549014/diff/29001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:174: devices, WebCams, etc.) and they cannot be claimed by user applications. On 2013/09/17 07:06:11, Andy wrote: > "WebCams" -> "webcams" (no capitals) Done. https://codereview.chromium.org/23549014/diff/29001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:387: <p>Isochronous transfer is the most complex type of USB transfer. They are On 2013/09/17 07:06:11, Andy wrote: > I still recommend using plural here: "Isochronous transfers are..." This would > match the <h3> header, as well as the first sentence in the sections that > describe the other types of transfers. > > If you stick with singular, I would start the second sentence with "Isochronous > transfers are commonly...". Done. https://codereview.chromium.org/23549014/diff/29001/chrome/common/extensions/... chrome/common/extensions/docs/templates/articles/app_hardware.html:648: are not accessible either because the Operating System's kernel or a native On 2013/09/17 07:06:11, Andy wrote: > "either because" -> "because either" Done.
CQ is trying da patch. Follow status at https://chromium-status.appspot.com/cq/ikarienator@chromium.org/23549014/32001
Message was sent while issue was closed.
Change committed as 224046 |
