Improve native messaging documentation

Improve native messaging documentation

- Specify format of NMH manifest.
- Specify the expected locations of the NMH on all platforms.
- Fully document the communication protocol and constraints.
- Document every error and offer tips for resolving the issues.
- Document other common problems and how-to-solve.

BUG=377582
R=sergeyu@chromium.org,kalman@chromium.org
NOTRY=true

Committed: https://crrev.com/0db8ee2ffb6efbce5f14a40729e8fd5eebf9d38f
Cr-Commit-Position: refs/heads/master@{#308420}

[robwu, 2014-12-02 20:45:58]

rob@robwu.nl changed required reviewers:
+ kalman@chromium.org, sergeyu@chromium.org

[robwu, 2014-12-02 20:45:58]

(re-uploaded issue, now with correct base URL)

Sergey: Please review when you're back.

kalman: Need your OWNER LG after Sergey's LG.
The native messaging docs span 6 pages after this CL. Does it make sense to move
the documentation to a separate page (e.g /{apps,extensions}/nativeMessaging)?

[Alexander Kashev, 2014-12-03 09:28:31]

mexmat.student@gmail.com changed reviewers:
+ mexmat.student@gmail.com

[Alexander Kashev, 2014-12-03 09:28:32]

As I've been asked on SO to provide commentary, if any, I'm publishing a couple
of line comments.

Also, I agree with Rob that the documentation grew enough (about a third of the
already big page) and is important enough as a separate topic to merit a
separate page.

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

https://codereview.chromium.org/768373004/diff/1/chrome/common/extensions/doc...
chrome/common/extensions/docs/templates/articles/messaging.html:307: <p>The
native messaging host manifest file must be valid JSON and contains the
I think the grammar here should be "must be ... and contain"

https://codereview.chromium.org/768373004/diff/1/chrome/common/extensions/doc...
chrome/common/extensions/docs/templates/articles/messaging.html:358: and set
default value of that key to the full path to the manifest file.<br>
Since you're updating the documentation: it would be great to specify how
backslashes in the path in the registry should be formatted. This has been a
source of confusion before (e.g.
http://stackoverflow.com/questions/21961775/chrome-native-messaging-on-windows);
it would be nice if there was a sample in the REG-file format.

https://codereview.chromium.org/768373004/diff/1/chrome/common/extensions/doc...
chrome/common/extensions/docs/templates/articles/messaging.html:402: hard limit
on the size of the message sent to the native messaging host.
Technically, not true: message sent to the host is limited by the 32-bit length
field.

[robwu, 2014-12-09 15:11:35]

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

https://codereview.chromium.org/768373004/diff/1/chrome/common/extensions/doc...
chrome/common/extensions/docs/templates/articles/messaging.html:307: <p>The
native messaging host manifest file must be valid JSON and contains the
On 2014/12/03 09:28:31, Alexander Kashev wrote:
> I think the grammar here should be "must be ... and contain"

The sentence is correct. Read the sentence as follows:

"The NMH manifest file (must be valid JSON) and (contains the following
fields)."

https://codereview.chromium.org/768373004/diff/1/chrome/common/extensions/doc...
chrome/common/extensions/docs/templates/articles/messaging.html:358: and set
default value of that key to the full path to the manifest file.<br>
On 2014/12/03 09:28:31, Alexander Kashev wrote:
> Since you're updating the documentation: it would be great to specify how
> backslashes in the path in the registry should be formatted. This has been a
> source of confusion before (e.g.
>
http://stackoverflow.com/questions/21961775/chrome-native-messaging-on-windows);
> it would be nice if there was a sample in the REG-file format.

The usual Windows path syntax applies. Paths are separated by a backslash, but
in contexts where a backslash is an escape character, two backslashes have to be
used. I have added three examples (2 inline in the documentation, one in a
separate file).

https://codereview.chromium.org/768373004/diff/1/chrome/common/extensions/doc...
chrome/common/extensions/docs/templates/articles/messaging.html:402: hard limit
on the size of the message sent to the native messaging host.
On 2014/12/03 09:28:32, Alexander Kashev wrote:
> Technically, not true: message sent to the host is limited by the 32-bit
length
> field.

Done.

[Sergey Ulanov, 2014-12-10 18:42:47]

Thanks for updating the docs!

https://codereview.chromium.org/768373004/diff/20001/chrome/common/extensions...
File chrome/common/extensions/docs/templates/articles/messaging.html (right):

https://codereview.chromium.org/768373004/diff/20001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/messaging.html:380: </p>
nit: don't need </p> here and below.
http://stackoverflow.com/questions/8460993/p-end-tag-p-is-not-needed-in-html

https://codereview.chromium.org/768373004/diff/20001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/messaging.html:473: <dt>Failed
to start native messaging host.</dt>
nit: don't need to close <dt>, same for <dd>

https://codereview.chromium.org/768373004/diff/20001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/messaging.html:490: <li>Is the
name spelled correctly in the extension and in the manifest file?</li>
nit: don't need to close <li> in html

https://codereview.chromium.org/768373004/diff/20001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/messaging.html:539:
<code>O_BINARY</code></b>. By default, the I/O mode is <code>O_TEXT</code>,
Please add link to MSDN for how the mode can be changed (e.g.
http://msdn.microsoft.com/en-us/library/tw4k6df8.aspx ).
IMO, the explanation of the side effects in the text mode and why it fails
doesn't need to be so detailed, I would limit it to 1 or 2 sentences.

[robwu, 2014-12-10 23:09:41]

Done. And also added the suggested change in the documentation to the Python
sample.

https://codereview.chromium.org/768373004/diff/20001/chrome/common/extensions...
File chrome/common/extensions/docs/templates/articles/messaging.html (right):

https://codereview.chromium.org/768373004/diff/20001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/messaging.html:380: </p>
On 2014/12/10 18:42:47, Sergey Ulanov wrote:
> nit: don't need </p> here and below.
> http://stackoverflow.com/questions/8460993/p-end-tag-p-is-not-needed-in-html

Done.

https://codereview.chromium.org/768373004/diff/20001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/messaging.html:473: <dt>Failed
to start native messaging host.</dt>
On 2014/12/10 18:42:47, Sergey Ulanov wrote:
> nit: don't need to close <dt>, same for <dd>

Done.

https://codereview.chromium.org/768373004/diff/20001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/messaging.html:490: <li>Is the
name spelled correctly in the extension and in the manifest file?</li>
On 2014/12/10 18:42:47, Sergey Ulanov wrote:
> nit: don't need to close <li> in html

Done.

https://codereview.chromium.org/768373004/diff/20001/chrome/common/extensions...
chrome/common/extensions/docs/templates/articles/messaging.html:539:
<code>O_BINARY</code></b>. By default, the I/O mode is <code>O_TEXT</code>,
On 2014/12/10 18:42:47, Sergey Ulanov wrote:
> Please add link to MSDN for how the mode can be changed (e.g.
> http://msdn.microsoft.com/en-us/library/tw4k6df8.aspx ).
> IMO, the explanation of the side effects in the text mode and why it fails
> doesn't need to be so detailed, I would limit it to 1 or 2 sentences.

Done.

[Sergey Ulanov, 2014-12-11 17:20:30]

LGTM with 2 nits. But I'm not an owner. Please wait for kalman@ to review.

https://codereview.chromium.org/768373004/diff/40001/chrome/common/extensions...
File
chrome/common/extensions/docs/examples/api/nativeMessaging/host/install_host.bat
(right):

https://codereview.chromium.org/768373004/diff/40001/chrome/common/extensions...
chrome/common/extensions/docs/examples/api/nativeMessaging/host/install_host.bat:1:
:: Change HKCU to HKLM if you want to install globally.
Please add copyright header in this file.

https://codereview.chromium.org/768373004/diff/40001/chrome/common/extensions...
File
chrome/common/extensions/docs/examples/api/nativeMessaging/host/uninstall_host.bat
(right):

https://codereview.chromium.org/768373004/diff/40001/chrome/common/extensions...
chrome/common/extensions/docs/examples/api/nativeMessaging/host/uninstall_host.bat:1:
:: Deletes the entry created by install_host.bat
copyright header please

[not at google - send to devlin, 2014-12-11 17:29:25]

I am happy to rubberstamp lgtm this if Sergey is ok with it.

[robwu, 2014-12-11 21:51:19]

Sergey, one more change. I've moved the NM docs to a new page, and made the
following hanges. Still LG?

messaging (preview):
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/messaging#nat...
- #native-messaging - The whole native messaging section has been replaced with
a short paragraph that refers to nativeMessaging.
- #examples - The sample now refers to the nativeMessaging page.

nativeMessaging (new! preview):
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/nativeMessaging
- Introduction - links back to messaging.
- #examples - Explains how to use the sample code.

[Alexander Kashev, 2014-12-11 23:11:36]

On 2014/12/11 21:51:19, robwu wrote:
> Sergey, one more change. I've moved the NM docs to a new page, and made the
> following hanges. Still LG?
> 
> messaging (preview):
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/messaging#nat...
> - #native-messaging - The whole native messaging section has been replaced
with
> a short paragraph that refers to nativeMessaging.
> - #examples - The sample now refers to the nativeMessaging page.
> 
> nativeMessaging (new! preview):
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/nativeMessaging
> - Introduction - links back to messaging.
> - #examples - Explains how to use the sample code.

What about existing links (say, on SO) that link to anchors within the removed
portion?

Namely, #native-messaging-host and #native-messaging-client

It would be nice if those fragments still led to the same paragraph.

[Alexander Kashev, 2014-12-11 23:12:30]

On 2014/12/11 23:11:36, Alexander Kashev wrote:
> On 2014/12/11 21:51:19, robwu wrote:
> > Sergey, one more change. I've moved the NM docs to a new page, and made the
> > following hanges. Still LG?
> > 
> > messaging (preview):
> >
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/messaging#nat...
> > - #native-messaging - The whole native messaging section has been replaced
> with
> > a short paragraph that refers to nativeMessaging.
> > - #examples - The sample now refers to the nativeMessaging page.
> > 
> > nativeMessaging (new! preview):
> >
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/nativeMessaging
> > - Introduction - links back to messaging.
> > - #examples - Explains how to use the sample code.
> 
> What about existing links (say, on SO) that link to anchors within the removed
> portion?
> 
> Namely, #native-messaging-host and #native-messaging-client
> 
> It would be nice if those fragments still led to the same paragraph.

"The same" = the new short paragraph, not a redirect to the new page.

[Alexander Kashev, 2014-12-11 23:14:39]

On 2014/12/11 23:12:30, Alexander Kashev wrote:
> On 2014/12/11 23:11:36, Alexander Kashev wrote:
> > On 2014/12/11 21:51:19, robwu wrote:
> > > Sergey, one more change. I've moved the NM docs to a new page, and made
the
> > > following hanges. Still LG?
> > > 
> > > messaging (preview):
> > >
> >
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/messaging#nat...
> > > - #native-messaging - The whole native messaging section has been replaced
> > with
> > > a short paragraph that refers to nativeMessaging.
> > > - #examples - The sample now refers to the nativeMessaging page.
> > > 
> > > nativeMessaging (new! preview):
> > >
> >
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/nativeMessaging
> > > - Introduction - links back to messaging.
> > > - #examples - Explains how to use the sample code.
> > 
> > What about existing links (say, on SO) that link to anchors within the
removed
> > portion?
> > 
> > Namely, #native-messaging-host and #native-messaging-client
> > 
> > It would be nice if those fragments still led to the same paragraph.
> 
> "The same" = the new short paragraph, not a redirect to the new page.

Oh, sorry, you already do that. Disregard.

[Sergey Ulanov, 2014-12-15 19:18:52]

On 2014/12/11 21:51:19, robwu wrote:
> Sergey, one more change. I've moved the NM docs to a new page, and made the
> following hanges. Still LG?
> 
> messaging (preview):
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/messaging#nat...
> - #native-messaging - The whole native messaging section has been replaced
with
> a short paragraph that refers to nativeMessaging.
> - #examples - The sample now refers to the nativeMessaging page.
> 
> nativeMessaging (new! preview):
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/nativeMessaging
> - Introduction - links back to messaging.
> - #examples - Explains how to use the sample code.

Still LGTM, except that I don't see navigation panel on the right of the new
page. Is that a problem with https://chrome-apps-doc.appspot.com ? Do you see
sidenav when running the server on your machine?

[robwu, 2014-12-15 19:26:38]

On 2014/12/15 19:18:52, Sergey Ulanov wrote:
> On 2014/12/11 21:51:19, robwu wrote:
> > Sergey, one more change. I've moved the NM docs to a new page, and made the
> > following hanges. Still LG?
> > 
> > messaging (preview):
> >
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/messaging#nat...
> > - #native-messaging - The whole native messaging section has been replaced
> with
> > a short paragraph that refers to nativeMessaging.
> > - #examples - The sample now refers to the nativeMessaging page.
> > 
> > nativeMessaging (new! preview):
> >
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/nativeMessaging
> > - Introduction - links back to messaging.
> > - #examples - Explains how to use the sample code.
> 
> Still LGTM, except that I don't see navigation panel on the right of the new
> page. Is that a problem with https://chrome-apps-doc.appspot.com ? Do you see
> sidenav when running the server on your machine?

I do see the nav at that appspot URL: http://i.imgur.com/yG7rYRt.png

[robwu, 2014-12-15 19:26:51]

The CQ bit was checked by rob@robwu.nl

[commit-bot: I haz the power, 2014-12-15 19:27:34]

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

[Sergey Ulanov, 2014-12-15 19:28:12]

The CQ bit was unchecked by sergeyu@chromium.org

[Sergey Ulanov, 2014-12-15 19:28:58]

On 2014/12/15 19:26:38, robwu wrote:
> On 2014/12/15 19:18:52, Sergey Ulanov wrote:
> > On 2014/12/11 21:51:19, robwu wrote:
> > > Sergey, one more change. I've moved the NM docs to a new page, and made
the
> > > following hanges. Still LG?
> > > 
> > > messaging (preview):
> > >
> >
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/messaging#nat...
> > > - #native-messaging - The whole native messaging section has been replaced
> > with
> > > a short paragraph that refers to nativeMessaging.
> > > - #examples - The sample now refers to the nativeMessaging page.
> > > 
> > > nativeMessaging (new! preview):
> > >
> >
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/nativeMessaging
> > > - Introduction - links back to messaging.
> > > - #examples - Explains how to use the sample code.
> > 
> > Still LGTM, except that I don't see navigation panel on the right of the new
> > page. Is that a problem with https://chrome-apps-doc.appspot.com ? Do you
see
> > sidenav when running the server on your machine?
> 
> I do see the nav at that appspot URL: http://i.imgur.com/yG7rYRt.png

Nope, you see the same that I see. Compare nav bars on
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/messaging and
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/nativeMessaging
.

[commit-bot: I haz the power, 2014-12-15 19:29:07]

The CQ bit was unchecked by commit-bot@chromium.org

[Sergey Ulanov, 2014-12-15 19:30:16]

On 2014/12/15 19:28:58, Sergey Ulanov wrote:
> On 2014/12/15 19:26:38, robwu wrote:
> > On 2014/12/15 19:18:52, Sergey Ulanov wrote:
> > > Still LGTM, except that I don't see navigation panel on the right of the
new
> > > page. Is that a problem with https://chrome-apps-doc.appspot.com ? Do you
> see
> > > sidenav when running the server on your machine?
> > 
> > I do see the nav at that appspot URL: http://i.imgur.com/yG7rYRt.png
> 
> Nope, you see the same that I see. Compare nav bars on
> https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/messaging and
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/nativeMessaging
> .

Specifically I think there must be some content inside of the grey box above the
"Contents" line.

[robwu, 2014-12-15 21:09:29]

On 2014/12/15 19:30:16, Sergey Ulanov wrote:
> On 2014/12/15 19:28:58, Sergey Ulanov wrote:
> > On 2014/12/15 19:26:38, robwu wrote:
> > > On 2014/12/15 19:18:52, Sergey Ulanov wrote:
> > > > Still LGTM, except that I don't see navigation panel on the right of the
> new
> > > > page. Is that a problem with https://chrome-apps-doc.appspot.com ? Do
you
> > see
> > > > sidenav when running the server on your machine?
> > > 
> > > I do see the nav at that appspot URL: http://i.imgur.com/yG7rYRt.png
> > 
> > Nope, you see the same that I see. Compare nav bars on
> > https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/messaging
and
> >
>
https://chrome-apps-doc.appspot.com/_patch/768373004/extensions/nativeMessaging
> > .
> 
> Specifically I think there must be some content inside of the grey box above
the
> "Contents" line.

I see. This appearance is not specific to the new nativeMessaging docs, the nav
("related pages") is also missing from apps/messaging
(https://developer.chrome.com/apps/messaging).
I've created a new ticket at https://crbug.com/442471. The absence of the TOC is
not critical for the documentation itself, are you fine with landing the CL and
editing the TOC later (if necessary)? If so, set the commit bit.

[Sergey Ulanov, 2014-12-15 21:21:23]

The CQ bit was checked by sergeyu@chromium.org

[commit-bot: I haz the power, 2014-12-15 21:22:43]

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

[commit-bot: I haz the power, 2014-12-15 21:24:02]

Committed patchset #6 (id:90001)

[commit-bot: I haz the power, 2014-12-15 21:24:52]

Patchset 6 (id:??) landed as
https://crrev.com/0db8ee2ffb6efbce5f14a40729e8fd5eebf9d38f
Cr-Commit-Position: refs/heads/master@{#308420}