Adding dev documentation for chrome.location

chrome/common/extensions/docs/templates/intros/location.html

+<p id="classSummary">
+Use the <code>chrome.location</code> API to retrieve geographical location of

[Jeffrey Yasskin, 2013/07/23 20:37:29]

I suspect this paragraph belongs in the "description" field of the API
definition, but I'm not sure where that goes in .idl files. In a .json, it would
be
https://code.google.com/p/chromium/codesearch/#chromium/src/chrome/common/ext....
Maybe it's the comment above the namespace for a .idl file?

You can cd to chrome/common/extensions/docs and run server2/preview.py to see
how your change will look, even though the public preview server is broken.

Ben, it would be nice to have a howto for this. What's an appropriate place to
put it? Maybe something under
http://www.chromium.org/developers/design-documents/extensions/how-the-extens...
(Have you updated those pages at all for the new documentation system?)

[not at google - send to devlin, 2013/07/23 20:41:04]

There is a README in chrome/common/extensions/docs but I guess this needs to be
more obvious.
Definitely not.

[vadimt, 2013/07/24 19:36:45]

Running preview.py results in:
D:\src\Chromium1\src\chrome\common\extensions\docs>python server2/preview.py
Traceback (most recent call last):
  File "server2/preview.py", line 40, in <module>
    from local_renderer import LocalRenderer
  File
"D:\src\Chromium1\src\chrome\common\extensions\docs\server2\local_renderer.py",
line 9, in <module>
    from server_instance import ServerInstance
  File
"D:\src\Chromium1\src\chrome\common\extensions\docs\server2\server_instance.py",
line 12, in <module>
    from manifest_data_source import ManifestDataSource
  File
"D:\src\Chromium1\src\chrome\common\extensions\docs\server2\manifest_data_source.py",
line 5, in <module>
    from collections import OrderedDict
ImportError: cannot import name OrderedDict

I'm not a big specialist in Python; does anyone have an idea what's happening.
(Please don't answer that this simply cannot work on Windows :))

+  the  hosting machine.</p>
+
+<h2 id="manifest">Manifest</h2>

[Jeffrey Yasskin, 2013/07/23 20:37:29]

Since there's nothing for someone to do in the manifest other than specify the
API permission, I think we should omit this section. It'll be mentioned in the
"Permissions" section of the header table anyway.

... Woah, I found a new file. You should update
docs/templates/json/intro_tables.json to make sure chrome.location gets a
Permissions section. This really needs better documentation...

[not at google - send to devlin, 2013/07/23 20:41:04]

We are supposed to be automatically generating the permissions. Dang. I'll get
somebody to work on it.

[vadimt, 2013/07/24 19:36:45]

Done.

+<p>You must declare the "location" permission
+  in the <a href="manifest.html">extension manifest</a>
+  to use the location API.
+  For example:
+</p>
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"permissions": [
+    "location"
+  ]</b>,
+  ...
+}</pre>
+
+<h2 id="description">Objects and properties</h2>
+<p>
+  To create a location watch, call $ref:chrome.location.watchLocation passing in
+  the location watch details via the <code>requestInfo</code> parameter:
+</p>
+<pre>chrome.location.watchLocation(name, requestInfo);</pre>
+<p>
+  You'll also need to add a listener
+  to its <code>onChanged</code> event.
+  Chrome will fire this event after you create your location watch. After this,
+  it will keep firing the event every time the geographical location of your
+  computer changes until you call $ref:chrome.location.clearWatch.
+</p>
+<p>
+  Here's sample code
+  to listen for location updates:
+</p>
+<pre>
+  chrome.location.onLocationUpdate.addListener(function(position) {
+    console.log(JSON.stringify(position));
+  });
+</pre>