Update function/nodejs docs for node.done changes

Author: knolleary

docs/creating-nodes/node-js.md

@@ -45,21 +45,88 @@ RED.nodes.registerType("sample",SampleNode);
 Nodes register a listener on the `input` event to receive messages from the
 up-stream nodes in a flow.
 
+With Node-RED 1.0, a new style of listener was introduced to allow the node
+to notify the runtime when it has finished handling a message. This added
+two new parameters to the listener function. Some care is needed to ensure
+the node can still be installed in Node-RED 0.x which does not use this new
+style of listener.
+
 {% highlight javascript %}
-this.on('input', function(msg) {
+this.on('input', function(msg, send, done) {
     // do something with 'msg'
+
+    // Once finished, call 'done'.
+    // This call is wrapped in a check that 'done' exists
+    // so the node will work in earlier versions of Node-RED (<1.0)
+    if (done) {
+        done();
+    }
 });
 {% endhighlight %}
 
+#### Handling errors
+
+If the node encounters an error whilst handling the message, it should pass
+the details of the error to the `done` function.
+
+This will trigger any Catch nodes present on the same tab, allowing the user to
+build flows to handle the error.
+
+Again, some care is needed in the case the node is installed in Node-RED 0.x which
+does not provide the `done` function. In that case, it should use `node.error`:
+
+
+{% highlight javascript %}
+let node = this;
+this.on('input', function(msg, send, done) {
+    // do something with 'msg'
+
+    // If an error is hit, report it to the runtime
+    if (err) {
+        if (done) {
+            // Node-RED 1.0 compatible
+            done(err);
+        } else {
+            // Node-RED 0.x compatible
+            node.error(err, msg);
+        }
+    }
+});
+{% endhighlight %}
+
+
 ### Sending messages
 
-Nodes can send messages to the down-stream nodes in a flow using the `send` function:
+If the node sits at the start of the flow and produces messages in response to
+external events, it should use the `send` function on the Node object:
 
 {% highlight javascript %}
 var msg = { payload:"hi" }
 this.send(msg);
 {% endhighlight %}
 
+If the node wants to send from inside the `input` event listener, in response to
+receiving a message, it should use the `send` function that is passed to the listener
+function:
+
+{% highlight javascript %}
+let node = this;
+this.on('input', function(msg, send, done) {
+    // For maximum backwards compatibility, check that send exists.
+    // If this node is installed in Node-RED 0.x, it will need to
+    // fallback to using `node.send`
+    send = send || function() { node.send.apply(node,arguments) }
+
+    msg.payload = "hi";
+    send(msg);
+
+    if (done) {
+        done();
+    }
+});
+{% endhighlight %}
+
+
 If `msg` is null, no message is sent.
 
 If the node is sending a message in response to having received one, it should reuse
@@ -154,24 +221,8 @@ this.debug("Log something more details for debugging the node's behaviour");
 
 {% endhighlight %}
 
-
 The `warn` and `error` messages also get sent to the flow editor debug tab.  
 
-#### Handling errors
-
-If the node encounters an error that should halt the current flow, it should log
-the event with the `this.error` function.
-
-If the error is one that a user of the node may want to handle for themselves,
-the function should be called with the original message (or an empty message if
-this is an Input node) as the second argument:
-
-{% highlight javascript %}
-node.error("hit an error", msg);
-{% endhighlight %}
-
-This will trigger any Catch nodes present on the same tab.
-
 ### Setting status
 
 Whilst running, a node is able to share status information with the editor UI.

docs/user-guide/writing-functions.md

@@ -108,15 +108,58 @@ If the function needs to perform an asynchronous action before sending a message
 it cannot return the message at the end of the function.
 
 Instead, it must make use of the `node.send()` function, passing in the message(s)
-to be sent. For example:
+to be sent. It takes the same arrangement of messages as that can be returned, as
+described in the previous sections.
+
+ For example:
+
+{% highlight javascript %}
+doSomeAsyncWork(msg, function(result) {
+    msg.payload = result;
+    node.send(msg);
+});
+return;
+{% endhighlight %}
+
+**Since Node-RED 1.0**
+
+The Function node will clone every message object you pass to `node.send` to
+ensure there is no unintended modification of message objects that get reused
+in the function. Before Node-RED 1.0, the Function node would not clone the
+*first* message passed to `node.send`, but would clone the rest.
+
+The Function can request the runtime to *not clone* the first message passed to
+`node.send` by passing in `false` as a second argument to the function. It would
+do this is the message contains something that is not otherwise cloneable, or for
+performance reasons to minimise the overhead of sending messages:
+
+{% highlight javascript %}
+node.send(msg,false);
+{% endhighlight %}
+
+#### Finishing with a message
+
+**Since Node-RED 1.0**
+
+If a Function node does asynchronous work with a message, the runtime will not
+automatically know when it has finished handling the message.
+
+To help it do so, the Function node should call `node.done()` at the appropriate
+time. This will allow the runtime to properly track messages through the system.
 
 {% highlight javascript %}
 doSomeAsyncWork(msg, function(result) {
-    node.send({payload:result});
+    msg.payload = result;
+    node.send(msg);
+    node.done();
 });
 return;
 {% endhighlight %}
 
+
+
+### Tidying up
+
 If you do use asynchronous callback code in your functions then you may need to
 tidy up any outstanding requests, or close any connections,  whenever the flow gets
 re-deployed. You can do this by adding a `close` event handler.
@@ -359,6 +402,7 @@ The following objects are available within the Function node.
  * `node.on(..)` : [register an event handler](#sending-messages-asynchronously)
  * `node.status(..)` : [update the node status](#adding-status)
  * `node.send(..)` : [send a message](#sending-messages-asynchronously)
+ * `node.done(..)` : [finish with a message](#finishing-with-a-message)
 
 #### `context`
  * `context.get(..)` : get a node-scoped context property