Fix explanation in runtime.onMessage doc

[sideshowbarker]

Fixes #1452

[github-actions]

Preview URLs

• https://pr3903.content.dev.mdn.mozit.cloud/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage

Flaws

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage
Title: runtime.onMessage
on GitHub
Flaw count: 3

• broken_links:
  • No need for the pathname in anchor links if it's the same page
  • No need for the pathname in anchor links if it's the same page
  • No need for the pathname in anchor links if it's the same page

External URLs

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage
Title: runtime.onMessage
on GitHub

No new external URLs

(this comment was updated 2021-05-19 07:08:35.068293)

[github-actions]

Preview URLs

• https://pr3903.content.dev.mdn.mozit.cloud/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage

Flaws

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage
Title: runtime.onMessage
on GitHub

No flaws! 🎉

External URLs

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage
Title: runtime.onMessage
on GitHub

• https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json (1 time)
• https://developer.chrome.com/extensions/runtime (1 time)
• https://github.com/mozilla/webextension-polyfill (1 time)
• runtime.onMessage is broken mozilla/webextension-polyfill#16 (1 time)

[chrisdavidmills]

I think I'll leave this one to @muffinresearch , as it's more his area of specialty. You OK to review this one Stuart?

[muffinresearch]

These changes look ok to me but I'll defer this review to @rpl

[rpl]

@sideshowbarker my apologies for not reaching this sooner.

The new wording seems to be at least slightly better, but I have the feeling that it is still a bit open to be misread.

Let's see if we can improve it a bit more.
@sideshowbarker wdyt about the tweaks proposed below?

(by knowing in detail how that works on the implementation side does likely make me unintentionally biased on evaluating how clear it really is from an external reader perspective, and so your perspective on the tweaks I'm proposing is important as much as mine, if not even more).

[rpl]

Nit, I'm wondering if saying here If you pass to addListener an async function instead of If you call addListener using an async function would make it more clear that async function is referring to the parameter we pass to addListener not the function inside which we may be calling addListener.

@muffinresearch what do you think? I would like to hear your pov from an English form perspective (because I may be biased by how my brain automatically translate that phrase in my own language).

[muffinresearch]

I would suggest changing that slightly from If you pass to addListener an async function to If you pass an async function to addListener.

[rpl]

yep, that does sound better 👍

[sideshowbarker]

@rpl, @muffinresearch, thanks — change that line so that it now reads:

If you pass an async function to addListener(), the listener will return a Promise for every message it receives, preventing other listeners from responding

[rpl]

Nit, you must define the listener as a non-<code>async</code> function, return a Promise only for the messages the listener is meant to respond to, and undefined or false otherwise?

[sideshowbarker]

Thanks — changed that line so that it now reads:

If you only want the listener to respond to messages of a certain type, you must define the listener as a non-async function, and return a Promise only for the messages the listener is meant to respond to — and otherwise return false or undefined

[rpl]

@sideshowbarker Thanks, this version seems much more clear to me. r+ from my side.

@caitmuenster do you want to give this a quick look from an editorial perspective?

[caitmuenster]

This looks good to me! Thank you so much, @sideshowbarker!

[sideshowbarker]

Thanks all — gonna go ahead and merge now per #3903 (comment)