Fix some typos, broken links and other issues in extension docs

Fix some typos, broken links and other issues in extension docs

This CL fixes some typos, broken links and other small issues in extension docs. 

Thanks for Sunny Jerry (ratsunny@gmail.com). Some of these mistakes were discovered by him and listed at https://code.google.com/p/chrome-documentation-chs/source/browse/documentation/error_list.txt .

BUG=173630, 168952, 119535, 167355
TEST=none

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

[Mike West, 2013-02-11 08:21:53]

Thanks for making these changes, I appreciate it!

I've made two small notes, and I'd like someone who actually knows something
about the Downloads API to take a look at the IDL comment change.

Randy: Would you mind verifying that the two comments in the documents.idl are
corrected correctly? :)

https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/api/...
File chrome/common/extensions/api/bookmarks.json (right):

https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/api/...
chrome/common/extensions/api/bookmarks.json:505: "description": "Fired when a
bookmark import session is begun.  Expensive observers should ignore handle
onCreated updates until onImportEnded is fired.  Observers should still handle
other notifications immediately.",
Please drop "handle". "Expensive observers should ignore 'onCreated'
updates...".

https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/api/...
File chrome/common/extensions/api/downloads.idl (right):

https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/api/...
chrome/common/extensions/api/downloads.idl:194: // An identifier that is
persistent across browser sessions.
+rdsmith: I don't know this API wll enough to know which of these is which. :)

https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/docs...
File chrome/common/extensions/docs/templates/articles/faq.html (right):

https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/templates/articles/faq.html:233: usage.  However,
you have to modify the tracking code to pull
Please change "have" to "must" for clarity.

[方觉(Fang Jue), 2013-02-11 11:37:54]

Thanks for your review.

https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/api/...
File chrome/common/extensions/api/bookmarks.json (right):

https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/api/...
chrome/common/extensions/api/bookmarks.json:505: "description": "Fired when a
bookmark import session is begun.  Expensive observers should ignore handle
onCreated updates until onImportEnded is fired.  Observers should still handle
other notifications immediately.",
On 2013/02/11 08:21:53, Mike West (chromium) wrote:
> Please drop "handle". "Expensive observers should ignore 'onCreated'
> updates...".

Done.

https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/api/...
File chrome/common/extensions/api/downloads.idl (right):

https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/api/...
chrome/common/extensions/api/downloads.idl:194: // An identifier that is
persistent across browser sessions.
On 2013/02/11 08:21:53, Mike West (chromium) wrote:
> +rdsmith: I don't know this API wll enough to know which of these is which. :)

I just provide some context. DownloadQuery is used in the search method to
search for download items, which has nothing to do with changes in a download
item. DownloadDelta is used in the onChanged event, which does describe changes
in a download item.
Waiting for Randy's opinion :)

https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/docs...
File chrome/common/extensions/docs/templates/articles/faq.html (right):

https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/templates/articles/faq.html:233: usage.  However,
you have to modify the tracking code to pull
On 2013/02/11 08:21:53, Mike West (chromium) wrote:
> Please change "have" to "must" for clarity.

Done.

[Mike West, 2013-02-11 11:42:52]

LGTM, but please wait for Randy's opinion before landing this.

Thank you!

On 2013/02/11 11:37:54, 方觉(Fang Jue) wrote:
> Thanks for your review.
> 
>
https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/api/...
> File chrome/common/extensions/api/bookmarks.json (right):
> 
>
https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/api/...
> chrome/common/extensions/api/bookmarks.json:505: "description": "Fired when a
> bookmark import session is begun.  Expensive observers should ignore handle
> onCreated updates until onImportEnded is fired.  Observers should still handle
> other notifications immediately.",
> On 2013/02/11 08:21:53, Mike West (chromium) wrote:
> > Please drop "handle". "Expensive observers should ignore 'onCreated'
> > updates...".
> 
> Done.
> 
>
https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/api/...
> File chrome/common/extensions/api/downloads.idl (right):
> 
>
https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/api/...
> chrome/common/extensions/api/downloads.idl:194: // An identifier that is
> persistent across browser sessions.
> On 2013/02/11 08:21:53, Mike West (chromium) wrote:
> > +rdsmith: I don't know this API wll enough to know which of these is which.
:)
> 
> I just provide some context. DownloadQuery is used in the search method to
> search for download items, which has nothing to do with changes in a download
> item. DownloadDelta is used in the onChanged event, which does describe
changes
> in a download item.
> Waiting for Randy's opinion :)
> 
>
https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/docs...
> File chrome/common/extensions/docs/templates/articles/faq.html (right):
> 
>
https://codereview.chromium.org/12223068/diff/1/chrome/common/extensions/docs...
> chrome/common/extensions/docs/templates/articles/faq.html:233: usage. 
However,
> you have to modify the tracking code to pull
> On 2013/02/11 08:21:53, Mike West (chromium) wrote:
> > Please change "have" to "must" for clarity.
> 
> Done.

[Sunny, 2013-02-11 12:04:51]

On 2013/02/11 03:02:11, 方觉(Fang Jue) wrote:

Thanks for your patch.
我不会用SVN，也没用过codereview这个工具，帮我做了patch省了我好多事 ：）

[not at google - send to devlin, 2013-02-11 14:06:46]

lgtm, like Mike said, thanks!

The downloads API change looks right to me, but you can wait for Randy if you
like.

https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
File chrome/common/extensions/api/runtime.json (right):

https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
chrome/common/extensions/api/runtime.json:288: "description": "Sent after
onSuspend to indicate that the app won't be unloaded after all."
FYI: there's actually a lot more we could do with these sort of references;
$ref:onSuspend should create a link to it too (though I'm not 100% that will
actually work) - but fixing up all such references would be far too much effort
than I expect anybody to want to do.

Likewise below, chrome.runtime.reload() -> $ref:reload.

Anyway, feel free to fix that, or don't - thanks for fixing up all this other
stuff :)

https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
File chrome/common/extensions/docs/templates/articles/whats_new.html (right):

https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
chrome/common/extensions/docs/templates/articles/whats_new.html:200: now has a
<code>WINDOW_ID_CURRENT</code> property.
Could $ref:windows.WINDOW_ID_CURRENT directly but to be honest I don't think
this is actually worthy of being mentioned at all. Let's just delete it...

https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
File chrome/common/extensions/docs/templates/intros/browserAction.html (right):

https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
chrome/common/extensions/docs/templates/intros/browserAction.html:174: Google
Chrome's monochrome Chrome menu icon.
just "menu"

https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
File chrome/common/extensions/docs/templates/intros/pageCapture.html (right):

https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
chrome/common/extensions/docs/templates/intros/pageCapture.html:21: to use the
pageCapture API.
$ref:pageCapture

[Mike West, 2013-02-11 14:11:06]

On 2013/02/11 14:06:46, kalman wrote:
> The downloads API change looks right to me, but you can wait for Randy if you
> like.

If you're happy, I'm happy. I just wanted someone else to decide, since I
haven't looked at that API at all. :)

[Randy Smith (Not in Mondays), 2013-02-11 16:28:57]

On 2013/02/11 14:11:06, Mike West (chromium) wrote:
> On 2013/02/11 14:06:46, kalman wrote:
> > The downloads API change looks right to me, but you can wait for Randy if
you
> > like.
> 
> If you're happy, I'm happy. I just wanted someone else to decide, since I
> haven't looked at that API at all. :)

I want to do a bit more review of the downloads API change, if it's ok with you
guys--I took a look at it and went "What???", but about something we did, not
this change.  But this change touches it.  So if you could hold off for a couple
of hours I'd be grateful.

[Randy Smith (Not in Mondays), 2013-02-11 16:35:01]

So my big confusion is that I don't think that the download id persists across
browser sessions (we'd like it to, but it doesn't yet).  But that probably is
clearly not caused by this CL, and hence isn't your worry; I'll take it up with
Ben when he gets back.

But I am confused about the change, as indicated below.  Naively, I would have
thought that we'd define the download id in the main object (DownloadItem) and
then backref to that description from DownloadQuery and DownloadDelta.  Why
replicate the definition from DownloadItem in DownloadQuery, but not do so in
DownloadDelta?

https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
File chrome/common/extensions/api/downloads.idl (right):

https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
chrome/common/extensions/api/downloads.idl:194: // An identifier that is
persistent across browser sessions.
Why are you changing this text?  As I read it, this comment is a back-reference
to the description of id in DownloadItem above, and as such the original text
makes more sense to me.

[not at google - send to devlin, 2013-02-11 16:37:13]

https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
File chrome/common/extensions/api/downloads.idl (right):

https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
chrome/common/extensions/api/downloads.idl:194: // An identifier that is
persistent across browser sessions.
On 2013/02/11 16:35:02, rdsmith wrote:
> Why are you changing this text?  As I read it, this comment is a
back-reference
> to the description of id in DownloadItem above, and as such the original text
> makes more sense to me.

The original text seems wrong, and supposed to be on DownloadDelta (as moved) -
but you're right, something like "The <code>id</code> of the DownloadItem to
query" would be better.

[Randy Smith (Not in Mondays), 2013-02-11 18:10:15]

On 2013/02/11 16:37:13, kalman wrote:
>
https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
> File chrome/common/extensions/api/downloads.idl (right):
> 
>
https://chromiumcodereview.appspot.com/12223068/diff/1037/chrome/common/exten...
> chrome/common/extensions/api/downloads.idl:194: // An identifier that is
> persistent across browser sessions.
> On 2013/02/11 16:35:02, rdsmith wrote:
> > Why are you changing this text?  As I read it, this comment is a
> back-reference
> > to the description of id in DownloadItem above, and as such the original
text
> > makes more sense to me.
> 
> The original text seems wrong, and supposed to be on DownloadDelta (as moved)
-
> but you're right, something like "The <code>id</code> of the DownloadItem to
> query" would be better.

Just to minimize round trips: LGTM with a change such as the above.  If you want
to keep it the way it is now, let's do a round trip :-}.

[方觉(Fang Jue), 2013-02-12 03:27:14]

According to the discussion, the description of DownloadQuery.id is changed to
"The <code>id</code> of the $ref:DownloadItem to query.".


Also fixed another legacy Developer mode reference in packaging.html (as it is
in faq.html).

https://codereview.chromium.org/12223068/diff/1037/chrome/common/extensions/a...
File chrome/common/extensions/api/runtime.json (right):

https://codereview.chromium.org/12223068/diff/1037/chrome/common/extensions/a...
chrome/common/extensions/api/runtime.json:288: "description": "Sent after
onSuspend to indicate that the app won't be unloaded after all."
On 2013/02/11 14:06:46, kalman wrote:
> FYI: there's actually a lot more we could do with these sort of references;
> $ref:onSuspend should create a link to it too (though I'm not 100% that will
> actually work) - but fixing up all such references would be far too much
effort
> than I expect anybody to want to do.
> 
> Likewise below, chrome.runtime.reload() -> $ref:reload.
> 
> Anyway, feel free to fix that, or don't - thanks for fixing up all this other
> stuff :)

Actually, there are inconsintencies around the docs about choices from:
someMethod
<code>someMethod</code>
<code>someMethod()</code>
<code>chrome.someApi.someMethod</code>
$ref:someApi.someMethod
and even <code>$ref:someApi.someMethod</code>
Fixing up all these would certainly improve the docs (and I personaly prefer
$ref's), but it probably should be another CL and maybe you should first discuss
and standardize which way to use.

('$ref:onSuspend' does work!)

https://codereview.chromium.org/12223068/diff/1037/chrome/common/extensions/d...
File chrome/common/extensions/docs/templates/articles/whats_new.html (right):

https://codereview.chromium.org/12223068/diff/1037/chrome/common/extensions/d...
chrome/common/extensions/docs/templates/articles/whats_new.html:200: now has a
<code>WINDOW_ID_CURRENT</code> property.
On 2013/02/11 14:06:46, kalman wrote:
> Could $ref:windows.WINDOW_ID_CURRENT directly but to be honest I don't think
> this is actually worthy of being mentioned at all. Let's just delete it...

Then delete it.

https://codereview.chromium.org/12223068/diff/1037/chrome/common/extensions/d...
File chrome/common/extensions/docs/templates/intros/browserAction.html (right):

https://codereview.chromium.org/12223068/diff/1037/chrome/common/extensions/d...
chrome/common/extensions/docs/templates/intros/browserAction.html:174: Google
Chrome's monochrome Chrome menu icon.
On 2013/02/11 14:06:46, kalman wrote:
> just "menu"

Done.

https://codereview.chromium.org/12223068/diff/1037/chrome/common/extensions/d...
File chrome/common/extensions/docs/templates/intros/pageCapture.html (right):

https://codereview.chromium.org/12223068/diff/1037/chrome/common/extensions/d...
chrome/common/extensions/docs/templates/intros/pageCapture.html:21: to use the
pageCapture API.
On 2013/02/11 14:06:46, kalman wrote:
> $ref:pageCapture

Other API docs don't use $ref here (since the target of the link is the same
page).

[Randy Smith (Not in Mondays), 2013-02-12 14:51:49]

Still LGTM.  Thanks!

[commit-bot: I haz the power, 2013-02-13 02:55:53]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/fangjue23303@gmail.com/12223068/5004

[commit-bot: I haz the power, 2013-02-13 08:50:40]

Change committed as 182168