Bluetooth: write documentation

Bluetooth: write documentation

Write an app_bluetooth page documenting the APIs for adapter state,
device information and discovery. Update links accordingly.

BUG=256728
R=armansito@chromium.org, mkearney@chromium.org

Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=256260

[keybuk, 2014-03-07 03:16:21]

mkearney: for OWNERS

[keybuk, 2014-03-07 03:30:24]

mkearney: for OWNERS

[keybuk, 2014-03-07 04:11:06]

I moved all the doc updates into this one CL, and removed from the other, to
make reviewing easier :-)

[armansito, 2014-03-09 05:51:33]

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
File chrome/common/extensions/docs/templates/articles/app_bluetooth.html
(right):

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:24:
"profiles": [ "1105", "1106" ]
We do allow specifying 128-bit UUIDs in the API, right? If so, I would change
one of the example UUIDs to 128-bit format, to show that various types of UUIDs
can be specified. This would be especially good for those who are new to
Bluetooth in general.

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:144:
<code>chrome.bluetooth.stopDiscovery</code> when done.
I would mention here that the call to startDiscovery shouldn't be conditional on
the adapter state and that the apps should always call this method if they
require discovery, as other apps might cause discovery to stop.

Unless, discovery state changes to false even though the app called
startDiscovery successfully before, in which case they should call it again, if
needed.

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:173:
chrome.bluetooth.getDevices(function(devices) {
The code is pretty self-explanatory, though I would add a comment line above
this call, something like "// Get devices that were already discovered."

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:218: you
must intead rely on information about the class or type of the device,
s/intead/instead/

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
File chrome/common/extensions/docs/templates/articles/manifest/bluetooth.html
(right):

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/manifest/bluetooth.html:17:
"profiles": [ "1105", "1106" ]
Add 128-bit UUID example to the list?

[keybuk, 2014-03-09 08:03:45]

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
File chrome/common/extensions/docs/templates/articles/app_bluetooth.html
(right):

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:24:
"profiles": [ "1105", "1106" ]
We only currently support 16-bit UUIDs - crbug.com/237582

The documentation can be changed later when that's fixed

[keybuk, 2014-03-09 16:24:38]

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
File chrome/common/extensions/docs/templates/articles/app_bluetooth.html
(right):

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:144:
<code>chrome.bluetooth.stopDiscovery</code> when done.
On 2014/03/09 05:51:33, armansito wrote:
> I would mention here that the call to startDiscovery shouldn't be conditional
on
> the adapter state and that the apps should always call this method if they
> require discovery, as other apps might cause discovery to stop.
> 
> Unless, discovery state changes to false even though the app called
> startDiscovery successfully before, in which case they should call it again,
if
> needed.

Done.

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:173:
chrome.bluetooth.getDevices(function(devices) {
On 2014/03/09 05:51:33, armansito wrote:
> The code is pretty self-explanatory, though I would add a comment line above
> this call, something like "// Get devices that were already discovered."

Done.

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:218: you
must intead rely on information about the class or type of the device,
On 2014/03/09 05:51:33, armansito wrote:
> s/intead/instead/

Done.

[armansito, 2014-03-09 18:38:10]

lgtm with one comment.

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
File chrome/common/extensions/docs/templates/articles/app_bluetooth.html
(right):

https://codereview.chromium.org/189263004/diff/60001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:24:
"profiles": [ "1105", "1106" ]
On 2014/03/09 08:03:45, keybuk wrote:
> We only currently support 16-bit UUIDs - crbug.com/237582
> 
> The documentation can be changed later when that's fixed

Oh, that's right. If someone DOES go and put in a 128-bit UUID in the manifest
file, I wonder if Chrome complains with an error when the extension gets
installed. If it doesn't, we should probably make it do so later. Either way,
should we add a note here for now that only 16-bit UUIDs can be specified?

[mkearney1, 2014-03-10 21:13:36]

lgtm with one main caveat (and lots of little nits):

You need to change the manifest bluetooth page title to be Manifest - Bluetooth
(consistency sake). 

Also, you need to link to this page from manifest.html (in sample manifest -
bluetooth).

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
File chrome/common/extensions/docs/templates/articles/app_bluetooth.html
(right):

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:1:
<h1>Bluetooth</h1>
Throughout this doc you say 'event does not begin discover of devices'. Wherever
you say this, add (see Discovering nearby devices) -- with proper a href.

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:29: To only
access adapter state, discover nearby devices and obtain basic
Small nit-- add comma after 'discover nearby devices'.

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:141: To
begin discovery of nearby devices use the
Small nit-- add comma between nearby devices and use 'nearby devices, use...'

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:143:
resource intensive so you should call
'discovery can be resource intensive...' should be its own sentence:

method. Discovery can be resource intensive...

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:160:
connected to, the event will not be sent, instead you should call
'instead you should call...' should be its own sentence: sent. Instead you
should call...'

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:205: matters
to your app you should watch the
Add comma between 'app' and 'you': 'matters to your app, you should...'

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:207:
<code>discovering</code> property changes to <code>false</code> then your app
Add comma between 'false' and 'then': '<code>false</code>, then your app...'

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:209: resume.
Be cautious of the resource intensive nature of discovery.
Is this caution important enough to put in a warning paragraph?

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:242: model,
and even revision, of a device from a vendor. Where it is not present
Add comma after 'present': 'Where it is not present, you...'

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
File chrome/common/extensions/docs/templates/articles/manifest/bluetooth.html
(right):

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/manifest/bluetooth.html:1:
<h1>bluetooth</h1>
This should be Manifest - Bluetooth like the other sections.

Also, you need to provide a link to this doc from manifest.html (where bluetooth
is in sample manifest).

[keybuk, 2014-03-11 17:03:37]

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
File chrome/common/extensions/docs/templates/articles/app_bluetooth.html
(right):

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:1:
<h1>Bluetooth</h1>
On 2014/03/10 21:13:37, mkearney1 wrote:
> Throughout this doc you say 'event does not begin discover of devices'.
Wherever
> you say this, add (see Discovering nearby devices) -- with proper a href.

Done.

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:29: To only
access adapter state, discover nearby devices and obtain basic
On 2014/03/10 21:13:37, mkearney1 wrote:
> Small nit-- add comma after 'discover nearby devices'.

Done.

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:29: To only
access adapter state, discover nearby devices and obtain basic
On 2014/03/10 21:13:37, mkearney1 wrote:
> Small nit-- add comma after 'discover nearby devices'.

Done.

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:141: To
begin discovery of nearby devices use the
On 2014/03/10 21:13:37, mkearney1 wrote:
> Small nit-- add comma between nearby devices and use 'nearby devices, use...'

Done.

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:143:
resource intensive so you should call
On 2014/03/10 21:13:37, mkearney1 wrote:
> 'discovery can be resource intensive...' should be its own sentence:
> 
> method. Discovery can be resource intensive...

Done.

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:160:
connected to, the event will not be sent, instead you should call
On 2014/03/10 21:13:37, mkearney1 wrote:
> 'instead you should call...' should be its own sentence: sent. Instead you
> should call...'

Done.

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:205: matters
to your app you should watch the
On 2014/03/10 21:13:37, mkearney1 wrote:
> Add comma between 'app' and 'you': 'matters to your app, you should...'

Done.

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:207:
<code>discovering</code> property changes to <code>false</code> then your app
On 2014/03/10 21:13:37, mkearney1 wrote:
> Add comma between 'false' and 'then': '<code>false</code>, then your app...'

Done.

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:209: resume.
Be cautious of the resource intensive nature of discovery.
On 2014/03/10 21:13:37, mkearney1 wrote:
> Is this caution important enough to put in a warning paragraph?

No, it's more just a continual reminder to enforce good practice of always
planning to stop the discovery

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/app_bluetooth.html:242: model,
and even revision, of a device from a vendor. Where it is not present
On 2014/03/10 21:13:37, mkearney1 wrote:
> Add comma after 'present': 'Where it is not present, you...'

Done.

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
File chrome/common/extensions/docs/templates/articles/manifest/bluetooth.html
(right):

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/manifest/bluetooth.html:1:
<h1>bluetooth</h1>
On 2014/03/10 21:13:37, mkearney1 wrote:
> This should be Manifest - Bluetooth like the other sections.
> 
> Also, you need to provide a link to this doc from manifest.html (where
bluetooth
> is in sample manifest).

Done.

https://codereview.chromium.org/189263004/diff/80001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/manifest/bluetooth.html:1:
<h1>bluetooth</h1>
On 2014/03/10 21:13:37, mkearney1 wrote:
> This should be Manifest - Bluetooth like the other sections.
> 
> Also, you need to provide a link to this doc from manifest.html (where
bluetooth
> is in sample manifest).

Done.

[keybuk, 2014-03-11 17:05:55]

Committed patchset #7 manually as r256260 (presubmit successful).