networking.config API: Add an example to the documentation.

networking.config API: Add an example to the documentation.

Also
 - makes the callback to finishAuthentication optional
 - adds the "Important: This API works only on Chrome OS."
   banner to the documentation page.

BUG=432280
Committed: https://crrev.com/5f12fa2b193e2f29d4d53b600facfaf9d1d7fef6
Cr-Commit-Position: refs/heads/master@{#320935}

[pneubeck (no reviews), 2015-03-13 14:05:31]

pneubeck@chromium.org changed reviewers:
+ cschuet@chromium.org, kalman@chromium.org

[pneubeck (no reviews), 2015-03-13 14:05:32]

ptal

[pneubeck (no reviews), 2015-03-13 14:06:46]

@Benjamin, I guess you will be interested in whether the usage of the framework
is idiomatic.
Christoph can take over reviewing the actual content.

[pneubeck (no reviews), 2015-03-13 14:07:14]

Using chrome/common/extensions/docs/server2/preview.py
it looks good.

[not at google - send to devlin, 2015-03-13 17:55:41]

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
File chrome/common/extensions/docs/templates/intros/networking_config.html
(right):

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:2: This
API allows an extension to implement an authenticator for captive portals.
It's nice to try to use "Extension" not "extension" in docs.

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:3: The
interaction between extension, Chrome OS and the user will be:
Try to use oxford commas, i.e. "Extension, Chrome OS, and the user..."

Btw is the correct terminology here "Chrome OS" or just "Chrome"?

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:4: <ul>
Should this be an ordered list?

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:8: network
list, badged with an icon to indicate that a captive portal handler is
"badged with an icon" --> "badged with your Extension's icon".

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:11:
connect as usual.</li>
I find this point confusing, what does "as usual" mean? And it seems to
contradict the next points. Perhaps it should be left out, then change the next
2 points to be:

<li>If the user selects such a network, but a captive portal is not detected,
Chrome will connect as usual - the extension will never be involved.
<li>Otherwise, if a captive portal is detected, the user is notified....

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:15: he
wants to authenticate using the registered extension or whether he wants
Avoid gender specific pronouns. In this case, you could rephrase this point
like:

"If a captive portal is detected, the user is notified and asked to authenticate
using the registered extension, or whether to visit the captive portal page."

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:18: the
$(ref:onCaptivePortalDetected) event.</li>
and:

"If the user selects the extension..."

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:21: can be
used as well.</li>
I don't understand this point, perhaps it needs to be reworded a bit.

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:25: 
It would helpful to include a few screenshots in here.

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:63: // If
required, interact with the user. E.g. to register him on first
s/him/them/

[pneubeck (no reviews), 2015-03-17 10:27:03]

didn't get to make Screenshots yet.

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
File chrome/common/extensions/docs/templates/intros/networking_config.html
(right):

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:2: This
API allows an extension to implement an authenticator for captive portals.
On 2015/03/13 17:55:41, kalman wrote:
> It's nice to try to use "Extension" not "extension" in docs.

Done.

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:3: The
interaction between extension, Chrome OS and the user will be:
On 2015/03/13 17:55:41, kalman wrote:
> Try to use oxford commas, i.e. "Extension, Chrome OS, and the user..."
> 
> Btw is the correct terminology here "Chrome OS" or just "Chrome"?

Done.

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:3: The
interaction between extension, Chrome OS and the user will be:
On 2015/03/13 17:55:41, kalman wrote:
> Try to use oxford commas, i.e. "Extension, Chrome OS, and the user..."
> 
> Btw is the correct terminology here "Chrome OS" or just "Chrome"?

it should be fine to use 'Chrome'. As long as the API is restricted to Chrome OS
there is anyways a disclaimer at the top of the page.

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:4: <ul>
On 2015/03/13 17:55:41, kalman wrote:
> Should this be an ordered list?

Semantically these steps happen in order.
I just find the numbers a bit distracting.

Done.

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:8: network
list, badged with an icon to indicate that a captive portal handler is
On 2015/03/13 17:55:40, kalman wrote:
> "badged with an icon" --> "badged with your Extension's icon".

As this highly debated about, I would not want to over-specify this (at least
until this stabilized more).
Also, the current implementation indeed uses a fixed icon and not the
extension's one.

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:11:
connect as usual.</li>
On 2015/03/13 17:55:40, kalman wrote:
> I find this point confusing, what does "as usual" mean? And it seems to
> contradict the next points. Perhaps it should be left out, then change the
next
> 2 points to be:
> 
> <li>If the user selects such a network, but a captive portal is not detected,
> Chrome will connect as usual - the extension will never be involved.
> <li>Otherwise, if a captive portal is detected, the user is notified....

Done.

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:15: he
wants to authenticate using the registered extension or whether he wants
On 2015/03/13 17:55:40, kalman wrote:
> Avoid gender specific pronouns. In this case, you could rephrase this point
> like:
> 
> "If a captive portal is detected, the user is notified and asked to
authenticate
> using the registered extension, or whether to visit the captive portal page."

Done.

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:18: the
$(ref:onCaptivePortalDetected) event.</li>
On 2015/03/13 17:55:40, kalman wrote:
> and:
> 
> "If the user selects the extension..."

Done.

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:21: can be
used as well.</li>
On 2015/03/13 17:55:40, kalman wrote:
> I don't understand this point, perhaps it needs to be reworded a bit.

Done.

https://codereview.chromium.org/1002243002/diff/1/chrome/common/extensions/do...
chrome/common/extensions/docs/templates/intros/networking_config.html:63: // If
required, interact with the user. E.g. to register him on first
On 2015/03/13 17:55:40, kalman wrote:
> s/him/them/

Done.

[not at google - send to devlin, 2015-03-17 14:35:11]

lgtm, great. I'll leave it to you to add screenshots (and in fact if it's easier
for you to submit this change as-is and add screenshots later, I'm fine with
that) - and try to specify a size so that there is no image pop-in.

https://codereview.chromium.org/1002243002/diff/20001/chrome/common/extension...
File chrome/common/extensions/docs/templates/intros/networking_config.html
(right):

https://codereview.chromium.org/1002243002/diff/20001/chrome/common/extension...
chrome/common/extensions/docs/templates/intros/networking_config.html:10: <li>If
the user selects such a network, but a captive portal is not detect,
detect -> detected

[pneubeck (no reviews), 2015-03-17 16:19:33]

The CQ bit was checked by pneubeck@chromium.org

[pneubeck (no reviews), 2015-03-17 16:19:35]

The patchset sent to the CQ was uploaded after l-g-t-m from kalman@chromium.org
Link to the patchset: https://codereview.chromium.org/1002243002/#ps40001
(title: "Fixed typo.")

[commit-bot: I haz the power, 2015-03-17 16:19:47]

CQ is trying da patch. Follow status at
 https://chromium-cq-status.appspot.com/patch-status/1002243002/40001

[commit-bot: I haz the power, 2015-03-17 17:31:20]

Committed patchset #3 (id:40001)

[commit-bot: I haz the power, 2015-03-17 17:32:50]

Patchset 3 (id:??) landed as
https://crrev.com/5f12fa2b193e2f29d4d53b600facfaf9d1d7fef6
Cr-Commit-Position: refs/heads/master@{#320935}