Adding dev documentation for chrome.location

chrome/common/extensions/api/location.idl

Index: chrome/common/extensions/api/location.idl
diff --git a/chrome/common/extensions/api/location.idl b/chrome/common/extensions/api/location.idl
index 0900c8fc8024b19a1de599599a9ad67e9e958aca..c9896de9bc98c48a742d520cd7f3880c0ddfd18d 100644
--- a/chrome/common/extensions/api/location.idl
+++ b/chrome/common/extensions/api/location.idl
@@ -3,9 +3,8 @@
 // found in the LICENSE file.
 // TODO(vadimt): Consider reusing WebKit/Blink types, if this is possible.
 
-// The <code>chrome.location</code> API augments the events from the
-// <a href="http://dev.w3.org/geo/api/spec-source.html">HTML Geolocation API</a>
-// to be event page compatible.
+// Use the <code>chrome.location</code> API to retrieve geographical location of
+// the hosting machine.

[not at google - send to devlin, 2013/07/27 01:51:49]

i preferred the old description

[vadimt, 2013/07/27 02:08:55]

That was a pretty head-scratchy description for the user :)

The user probably wants to see something more digestible and actionable, like:

Use the chrome.alarms API to schedule code to run periodically or at a specified
time in the future.

Also, it creates a false impression that the API is literally a wrapper around
that API, which is not true, despite the fact that they share 99% of
implementation.

[Jeffrey Yasskin, 2013/07/27 03:00:29]

Can we combine them? I agree that your new description is much better for new
users, but I think experienced HTML5 folks will wonder how it's different from
the geolocation API they already know, and why we invented our own. What if you
add a sentence "This is a version of the <a
href="http://dev.w3.org/geo/api/spec-source.html">HTML Geolocation API</a> that
is compatible with event pages." ?

[not at google - send to devlin, 2013/07/29 14:45:12]

Yes exactly. This was going to be my next comment. You need to make this clear
somewhere.

I like it in the description; I definitely want to see it in the intro section.

[vadimt, 2013/07/30 01:58:41]

Done. Probably, a similar comment should be done for chrome.alarms API?

 namespace location {
   // Coordinates part of the Location object.
   dictionary Coordinates {