Index: extensions/common/api/runtime.json |
diff --git a/extensions/common/api/runtime.json b/extensions/common/api/runtime.json |
index d4a4e5980caf3b1d614e24f683de7e6d10751ebd..3e88909b611353d4057ce9ad6c65973edca1d992 100644 |
--- a/extensions/common/api/runtime.json |
+++ b/extensions/common/api/runtime.json |
@@ -14,17 +14,35 @@ |
"id": "Port", |
"type": "object", |
"nocompile": true, |
- "description": "An object which allows two way communication with other pages.", |
+ "description": "An object which allows two way communication with other pages. See <a href=\"messaging#connect\">Long-lived connections</a> for more information.", |
"properties": { |
- "name": {"type": "string"}, |
- "disconnect": { "type": "function" }, |
- "onDisconnect": { "$ref": "events.Event" }, |
- "onMessage": { "$ref": "events.Event" }, |
- "postMessage": {"type": "function"}, |
+ "name": { |
+ "type": "string", |
+ "description": "The name of the port, as specified in the call to $(ref:runtime.connect)." |
+ }, |
+ "disconnect": { |
+ "type": "function", |
+ "description": "Immediately disconnect the port. Calling <code>disconnect()</code> on an already-disconnected port has no effect. When a port is disconnected, no <em>new</em> events are generated any more on this port. If <code>disconnect()</code> was called while dispatching an $(ref:Port.onMessage onMessage) event, then the existing handlers still continue to be fired for that event." |
Devlin
2016/04/13 20:15:33
remove "any more"
Devlin
2016/04/13 20:15:33
Here, too, I worry that we're getting too much int
robwu
2016/04/13 21:03:05
Done.
robwu
2016/04/13 21:03:05
Done.
|
+ }, |
+ "onDisconnect": { |
+ "$ref": "events.Event", |
+ "description": "Fired when the port is disconnected from the other end(s). $(ref:runtime.lastError) may be set if the port was disconnected by an error. If the port is closed via $(ref:Port.disconnect disconnect), then this event is <em>only</em> fired on the other end. This event is fired at most once (see also <a href=\"messaging#port-lifetime\">Port lifetime</a>). The first and only parameter to the event handler is this disconnected port." |
+ }, |
+ "onMessage": { |
+ "$ref": "events.Event", |
+ "description": "This event is fired when $(ref:Port.postMessage postMessage) is called by the other end of the port. The first parameter is the message, the second parameter is the port that received the message." |
+ }, |
+ "postMessage": { |
+ "type": "function", |
+ "description": "Send a message to the other end of the port. If the port is disconnected, an error is thrown.", |
+ "parameters": [ |
+ {"name": "message", "type": "any", "description": "The message to send. This object should be JSON-ifiable."} |
+ ] |
+ }, |
"sender": { |
"$ref": "MessageSender", |
"optional": true, |
- "description": "This property will <b>only</b> be present on ports passed to onConnect/onConnectExternal listeners." |
+ "description": "This property will <b>only</b> be present on ports passed to $(ref:runtime.onConnect onConnect) / $(ref:runtime.onConnectExternal onConnectExternal) listeners." |
} |
}, |
"additionalProperties": { "type": "any"} |
@@ -249,7 +267,7 @@ |
"name": "connect", |
"type": "function", |
"nocompile": true, |
- "description": "Attempts to connect to connect listeners within an extension/app (such as the background page), or other extensions/apps. This is useful for content scripts connecting to their extension processes, inter-app/extension communication, and <a href=\"manifest/externally_connectable.html\">web messaging</a>. Note that this does not connect to any listeners in a content script. Extensions may connect to content scripts embedded in tabs via <a href=\"extensions/tabs#method-connect\">tabs.connect</a>.", |
+ "description": "Attempts to connect to connect listeners within an extension/app (such as the background page), or other extensions/apps. This is useful for content scripts connecting to their extension processes, inter-app/extension communication, and <a href=\"manifest/externally_connectable.html\">web messaging</a>. Note that this does not connect to any listeners in a content script. Extensions may connect to content scripts embedded in tabs via $(ref:tabs.connect).", |
"parameters": [ |
{"type": "string", "name": "extensionId", "optional": true, "description": "The ID of the extension or app to connect to. If omitted, a connection will be attempted with your own extension. Required if sending messages from a web page for <a href=\"manifest/externally_connectable.html\">web messaging</a>."}, |
{ |
@@ -264,14 +282,15 @@ |
], |
"returns": { |
"$ref": "Port", |
- "description": "Port through which messages can be sent and received. The port's $(ref:runtime.Port onDisconnect) event is fired if the extension/app does not exist. " |
+ // TODO(robwu): This description should appear in the documentation, but the docserver does not render it. |
+ "description": "Port through which messages can be sent and received. The port's $(ref:Port onDisconnect) event is fired if the extension/app does not exist. " |
} |
}, |
{ |
"name": "connectNative", |
"type": "function", |
"nocompile": true, |
- "description": "Connects to a native application in the host machine.", |
+ "description": "Connects to a native application in the host machine. See <a href=\"nativeMessaging\">Native Messaging</a> for more information.", |
"parameters": [ |
{ |
"type": "string", |
@@ -289,10 +308,10 @@ |
"type": "function", |
"nocompile": true, |
"allowAmbiguousOptionalArguments": true, |
- "description": "Sends a single message to event listeners within your extension/app or a different extension/app. Similar to $(ref:runtime.connect) but only sends a single message, with an optional response. If sending to your extension, the $(ref:runtime.onMessage) event will be fired in each page, or $(ref:runtime.onMessageExternal), if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use <a href=\"extensions/tabs#method-sendMessage\">tabs.sendMessage</a>.", |
+ "description": "Sends a single message to event listeners within your extension/app or a different extension/app. Similar to $(ref:runtime.connect) but only sends a single message, with an optional response. If sending to your extension, the $(ref:runtime.onMessage) event will be fired in each page, or $(ref:runtime.onMessageExternal), if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use $(ref:tabs.sendMessage).", |
"parameters": [ |
{"type": "string", "name": "extensionId", "optional": true, "description": "The ID of the extension/app to send the message to. If omitted, the message will be sent to your own extension/app. Required if sending messages from a web page for <a href=\"manifest/externally_connectable.html\">web messaging</a>."}, |
- { "type": "any", "name": "message" }, |
+ { "type": "any", "name": "message", "description": "The message to send. This message should be JSON-ifiable object." }, |
{ |
"type": "object", |
"name": "options", |
@@ -467,7 +486,7 @@ |
"options": { |
"unmanaged": true |
}, |
- "description": "Fired when a connection is made from either an extension process or a content script.", |
+ "description": "Fired when a connection is made from either an extension process or a content script (by $(ref:runtime.connect)).", |
"parameters": [ |
{"$ref": "Port", "name": "port"} |
] |
@@ -476,7 +495,7 @@ |
"name": "onConnectExternal", |
"type": "function", |
"nocompile": true, |
- "description": "Fired when a connection is made from another extension.", |
+ "description": "Fired when a connection is made from another extension (by $(ref:runtime.connect)).", |
"parameters": [ |
{"$ref": "Port", "name": "port"} |
] |
@@ -488,11 +507,11 @@ |
"options": { |
"unmanaged": true |
}, |
- "description": "Fired when a message is sent from either an extension process or a content script.", |
+ "description": "Fired when a message is sent from either an extension process (by $(ref:runtime.sendMessage)) or a content script (by $(ref:tabs.sendMessage)).", |
"parameters": [ |
{"name": "message", "type": "any", "optional": true, "description": "The message sent by the calling script."}, |
{"name": "sender", "$ref": "MessageSender" }, |
- {"name": "sendResponse", "type": "function", "description": "Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one <code>onMessage</code> listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, unless you return true from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until <code>sendResponse</code> is called)." } |
+ {"name": "sendResponse", "type": "function", "description": "Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one <code>onMessage</code> listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, <strong>unless you return true</strong> from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until <code>sendResponse</code> is called)." } |
], |
"returns": { |
"type": "boolean", |
@@ -504,11 +523,11 @@ |
"name": "onMessageExternal", |
"type": "function", |
"nocompile": true, |
- "description": "Fired when a message is sent from another extension/app. Cannot be used in a content script.", |
+ "description": "Fired when a message is sent from another extension/app (by $(ref:runtime.sendMessage)). Cannot be used in a content script.", |
"parameters": [ |
{"name": "message", "type": "any", "optional": true, "description": "The message sent by the calling script."}, |
{"name": "sender", "$ref": "MessageSender" }, |
- {"name": "sendResponse", "type": "function", "description": "Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one <code>onMessage</code> listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, unless you return true from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until <code>sendResponse</code> is called)." } |
+ {"name": "sendResponse", "type": "function", "description": "Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one <code>onMessage</code> listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, <strong>unless you return true</strong> from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until <code>sendResponse</code> is called)." } |
], |
"returns": { |
"type": "boolean", |