Make the extension API docs point out the minimum version that supports an API call.

Make the extension API docs point out the minimum version that supports an API call.

BUG=41127
TEST=none

Committed: http://src.chromium.org/viewvc/chrome?view=rev&revision=51013

[Sam Kerner (Chrome), 2010-06-24 21:08:47]

The first patch set shows the files that were not generated by
docs/build/build.py .  The second change set includes the changed documentation
files.  

Ideas for less verbose wording are welcome.

[kathyw, 2010-06-24 21:25:57]

Some suggested wording changes (but I'm happy to see this change).

http://codereview.chromium.org/2812023/diff/2001/3042
File chrome/common/extensions/docs/template/api_template.html (right):

http://codereview.chromium.org/2812023/diff/2001/3042#newcode47
chrome/common/extensions/docs/template/api_template.html:47: It must be omitted
in earlier versions, and may be omitted in any
Let's make this less passive. How about:

You must omit this parameter in earlier versions,
and you may omit it in any version.
If you need to use this parameter,
use the manifest key <a...>...</a>
to ensure that your extension won't run in earlier versions.

http://codereview.chromium.org/2812023/diff/2001/3042#newcode353
chrome/common/extensions/docs/template/api_template.html:353: New in version
<b><span jscontent="$this.min_version"></span></b>.
Make this wording consistent with the above wording. Maybe:

This function was added in version...
If you need to use this function,
use the manifest key...

[Sam Kerner (Chrome), 2010-06-24 22:07:30]

http://codereview.chromium.org/2812023/diff/2001/3042
File chrome/common/extensions/docs/template/api_template.html (right):

http://codereview.chromium.org/2812023/diff/2001/3042#newcode47
chrome/common/extensions/docs/template/api_template.html:47: It must be omitted
in earlier versions, and may be omitted in any
On 2010/06/24 21:25:58, kathyw wrote:
> Let's make this less passive. How about:
> 
> You must omit this parameter in earlier versions,
> and you may omit it in any version.
> If you need to use this parameter,
> use the manifest key <a...>...</a>
> to ensure that your extension won't run in earlier versions.
> 

Good idea.  Done.

http://codereview.chromium.org/2812023/diff/2001/3042#newcode353
chrome/common/extensions/docs/template/api_template.html:353: New in version
<b><span jscontent="$this.min_version"></span></b>.
On 2010/06/24 21:25:58, kathyw wrote:
> Make this wording consistent with the above wording. Maybe:
> 
> This function was added in version...
> If you need to use this function,
> use the manifest key...

Done.

[rafaelw, 2010-06-24 22:15:50]

+cc: aa, just as an fyi

lgtm on the code & template changes.

[kathyw, 2010-06-25 16:32:40]

Just a couple of nits.

Do you have the generated doc staged somewhere I could look at it?

http://codereview.chromium.org/2812023/diff/9050/11042
File chrome/common/extensions/docs/template/api_template.html (right):

http://codereview.chromium.org/2812023/diff/9050/11042#newcode48
chrome/common/extensions/docs/template/api_template.html:48: and you may omit it
in any version.  If you use this
use -> require

(There's lots of occurrences of "use" in this sentence, plus couldn't you use
this parameter only sometimes, maybe after testing somehow whether you can use
it?)

http://codereview.chromium.org/2812023/diff/9050/11042#newcode51
chrome/common/extensions/docs/template/api_template.html:51: to ensure that your
extension won't be used in an earlier version of Chrome.
Chrome -> Google Chrome

Or just say "an earlier browser version".

[Sam Kerner (Chrome), 2010-06-25 19:33:32]

I put my updated docs here:

http://www.corp.google.com/~skerner/chromeDocs/minVersion/tabs.html#method-ca...

http://www.corp.google.com/~skerner/chromeDocs/minVersion/browserAction.html#...

http://codereview.chromium.org/2812023/diff/9050/11042
File chrome/common/extensions/docs/template/api_template.html (right):

http://codereview.chromium.org/2812023/diff/9050/11042#newcode48
chrome/common/extensions/docs/template/api_template.html:48: and you may omit it
in any version.  If you use this
On 2010/06/25 16:32:40, kathyw wrote:
> use -> require
> 
> (There's lots of occurrences of "use" in this sentence, plus couldn't you use
> this parameter only sometimes, maybe after testing somehow whether you can use
> it?)

A developer could get the version of chrome, and call the function in a
different way for different versions.  I can't think of a clean way to get the
version, and I don't want to explain the dirty way:

try {
  chrome.tab.captureVisibleTab(null, {...}, ...}, callback_fn);
} catch (e) {
  if (/*e is a type error for the second arg*/) {
    chrome.tab.captureVisibleTab(null, callback_fn);
  }
}

So the message I want to convey is: "Don't call this function in the new way
unless you know it will work.  minimum_chrome_version is a good method to do
this."  I don't want to tell people they can't do something ugly.  I also don't
want to recommend it.

There are three "use"es.  1st changed to "require".  Third changed to "run". 
Ideas for better phrasing are welcome.

http://codereview.chromium.org/2812023/diff/9050/11042#newcode51
chrome/common/extensions/docs/template/api_template.html:51: to ensure that your
extension won't be used in an earlier version of Chrome.
On 2010/06/25 16:32:40, kathyw wrote:
> Chrome -> Google Chrome
> 
> Or just say "an earlier browser version".

Done.

[kathyw, 2010-06-28 16:23:20]

LGTM