From dfe1cd4f90ab59fd9763083e3b83db1cbb6f4ae4 Mon Sep 17 00:00:00 2001
From: Nick O'Leary <nick.oleary@gmail.com>
Date: Tue, 23 May 2017 17:26:23 +0100
Subject: [PATCH] Tidy up more core node help text

---
 nodes/core/core/20-inject.html   | 38 +++++++++++++++-----------------
 nodes/core/core/25-catch.html    | 21 +++++++++---------
 nodes/core/core/58-debug.html    | 20 +++++++----------
 nodes/core/core/60-link.html     | 10 ---------
 nodes/core/core/80-function.html | 32 +++++++++++++++------------
 nodes/core/logic/10-switch.html  | 13 ++++++-----
 nodes/core/logic/15-change.html  |  8 +++----
 7 files changed, 65 insertions(+), 77 deletions(-)

diff --git a/nodes/core/core/20-inject.html b/nodes/core/core/20-inject.html
index 0151e08aa..5e149a273 100644
--- a/nodes/core/core/20-inject.html
+++ b/nodes/core/core/20-inject.html
@@ -150,28 +150,26 @@
     }
 </style>
 <script type="text/x-red" data-help-name="inject">
-<p>Injects a message with an optional topic into a flow by pressing the button on the left side of the node.
-Several payload javascript types can be injected at various intervals into the flow.</p>
-<p><b>Outputs</b></p>
-<ul>
-    <li><code>msg.payload</code> - <i>timestamp | string | number | boolean | JSON | flow | global</i></li>
-    <li><code><i>msg.topic</i></code> - <i>string</i> - optional meta-data</li>
-</ul>
-<p><b>Details</b></p>
+<p>Injects a message into a flow either manually or at regular intervals. The message
+payload can be a variety of types, including strings, JavaScript objects or the current time.</p>
+<h3>Outputs</h3>
+<dl class="message-properties">
+    <dt>payload<span class="property-type">various</span></dt>
+    <dd>The configured payload of the message.</dd>
+    <dt class="optional">topic <span class="property-type">string</span></dt>
+    <dd>An optional property</dd>
+</dl>
+<h3>Details</h3>
 <p>The Inject node can initiate a flow with a specific payload value.
-The default payload is a timestamp of the current time in millisecs since 1970.
-Strings, numbers, JSON objects, and booleans types can be injected.
-The <i>Flow</i> and <i>Global</i> options allow the user to inject a flow or global context value.</p>
-<p>The repeat function allows the payload to be sent on the required schedule - <i>Once</i>, at a <i>set interval</i>,
-between certain times (local time where the Node-RED process is running), or at a <i>specific interval</i>.</p>
-
-<p>The <i>Inject once at start</i> option actually waits a short interval before firing to give other nodes a chance to instantiate properly.</p>
-
-<p><b>Note</b>: <i>"Interval between times"</i> and <i>"at a specific time"</i> uses cron.
+The default payload is a timestamp of the current time in millisecs since January 1st, 1970.</p>
+<p>The node also supports injecting strings, numbers, booleans, JavaScript objects, or flow/global context values.</p>
+<p>By default, the node is triggered manually by clicking on its button within the editor. It can also be set to
+inject at regular intervals or according to a schedule.</p>
+<p>It can also be configured to inject once each time the flows are started.</p>
+<p><b>Note</b>: The <i>"Interval between times"</i> and <i>"at a specific time"</i> options use the standard cron system.
 This means that 20 minutes will be at the next hour, 20 minutes past and 40 minutes past - not in 20 minutes time.
-If you want every 20 minutes from now - use the "interval" option.</p>
-
-<p><b>Note</b>: all string input is escaped. To add a carriage return to a string you should use a following function.</p>
+If you want every 20 minutes from now - use the <i>"interval"</i> option.</p>
+<p><b>Note</b>: To include a newline in a string you must use a Function node to create the payload.</p>
 </script>
 
 <script type="text/javascript">
diff --git a/nodes/core/core/25-catch.html b/nodes/core/core/25-catch.html
index d9cfe0832..705ffb013 100644
--- a/nodes/core/core/25-catch.html
+++ b/nodes/core/core/25-catch.html
@@ -28,27 +28,26 @@
     <p>Catch errors thrown by nodes on the same tab.</p>
     <h3>Outputs</h3>
     <dl class="message-properties">
-        <dt>msg <span class="property-type">object</span></dt>
-        <dd>the original msg object message (if available).</dd>
-        <dt>msg.error.message <span class="property-type">string</span></dt>
+        <dt>error.message <span class="property-type">string</span></dt>
         <dd>the error message.</dd>
-        <dt>msg.error.source.id <span class="property-type">string</span></dt>
+        <dt>error.source.id <span class="property-type">string</span></dt>
         <dd>the id of the node that threw the error.</dd>
-        <dt>msg.error.source.type <span class="property-type">string</span></dt>
+        <dt>error.source.type <span class="property-type">string</span></dt>
         <dd>the type of the node that threw the error.</dd>
-        <dt>msg.error.source.name <span class="property-type">string</span></dt>
+        <dt>error.source.name <span class="property-type">string</span></dt>
         <dd>the name, if set, of the node that threw the error.</dd>
     </dl>
     <h3>Details</h3>
-    <p>If a node throws a error whilst handling a message, the flow will typically
+    <p>If a node throws an error whilst handling a message, the flow will typically
        halt. This node can be used to catch those errors and handle them with a
        dedicated flow.</p>
-    <p>The node will catch errors thrown by any node on the same tab. If there
-       are multiple catch nodes on a tab, they will all get triggered.</p>
+    <p>By default, the node will catch errors thrown by any node on the same tab. Alternatively
+    it can be targetted at specific nodes.</p>
+    <p>When an error is thrown, all matching catch nodes will receive the message.</p>
     <p>If an error is thrown within a subflow, the error will get handled by any
-       catch nodes within the subflow. If none exists, the error is propagated
+       catch nodes within the subflow. If none exists, the error will be propagated
        up to the tab the subflow instance is on.</p>
-   <p>If the message already had a <code>error</code> property, it is copied to <code>_error</code>.</p>
+   <p>If the message already has a <code>error</code> property, it is copied to <code>_error</code>.</p>
 </script>
 <style>
 #node-input-catch-target-container {
diff --git a/nodes/core/core/58-debug.html b/nodes/core/core/58-debug.html
index 278c3f6e1..ba987dcb1 100644
--- a/nodes/core/core/58-debug.html
+++ b/nodes/core/core/58-debug.html
@@ -19,18 +19,14 @@
 </script>
 
 <script type="text/x-red" data-help-name="debug">
-    <p>The Debug node can be connected to the output of any node. It can be used to display the output of any message
-    property in the debug tab of the sidebar. The default is to display <code>msg.payload</code>.</p>
-    <p>Each message will also display the date, time, node-id and the type of the chosen property.</p>
-    <p>The sidebar can be accessed under the options drop-down ( <i class="fa fa-bars"></i> ) in the top right corner.</p>
-    <p>The button to the right of the node will toggle its output on and off so you can de-clutter the debug window.</p>
-    <p>You can explore the received messages further by clicking on them. Numbers will be shown in decimal and hex and
-    as a timestamp if appropriate. Objects and arrays can be further expanded as required. Buffers may be able to be
-    shown as strings if possible.</p>
-    <p>Selecting the node-id of any particular message will highlight (in red) the debug node that reported it.
-    This is useful if you wire up multiple debug nodes.</p>
-    <p>The node can also be configured to send all messages to the console log (⇶).</p>
-    <p><b>Note: </b>In addition, any calls to <b>node.warn</b> or <b>node.error</b> will also appear in the debug tab.</p>
+    <p>Displays selected message properties in the debug sidebar tab and optionally the runtime log. By default it displays <code>msg.payload</code>.</p>
+    <h3>Details</h3>
+    <p>The debug sidebar provides a structured view of the messages it is sent, making it easier to understand their structure.</p>
+    <p>JavaScript objects and arrays can be collapsed and expanded as required. Buffer objects can be displayed as raw data or as a string if possible.</p>
+    <p>Alongside each message, the debug sidebar includes information about the time the message was received, the node that sent it and the type of the message.
+       Clicking on the source node id will reveal that node within the workspace.</p>
+    <p>The button on the node can be used to enable or disable its output. It is recommended to disable or remove any Debug nodes that are not being used.</p>
+    <p>The node can also be configured to send all messages to the runtime log.</p>
 </script>
 <script src="debug/view/debug-utils.js"></script>
 
diff --git a/nodes/core/core/60-link.html b/nodes/core/core/60-link.html
index 48c5de941..5092ba5b1 100644
--- a/nodes/core/core/60-link.html
+++ b/nodes/core/core/60-link.html
@@ -15,11 +15,6 @@
 </script>
 <script type="text/x-red" data-help-name="link in">
     <p>Create virtual wires between flows.</p>
-    <h3>Outputs</h3>
-    <dl class="message-properties">
-        <dt>msg <span class="property-type">object</span></dt>
-        <dd>a msg object that was sent to a link out node.</dd>
-    </dl>
     <h3>Details</h3>
     <p>The node can be connected to any <code>link out</code> node that exists on any tab.
        Once connected, they behave as if they were wired together.</p>
@@ -30,11 +25,6 @@
 </script>
 <script type="text/x-red" data-help-name="link out">
     <p>Create virtual wires between flows.</p>
-    <h3>Inputs</h3>
-    <dl class="message-properties">
-        <dt>msg <span class="property-type">object</span></dt>
-        <dd>a msg object to send to a link in node.</dd>
-    </dl>
     <h3>Details</h3>
     <p>The node can be connected to any <code>link in</code> node that exists on any tab.
        Once connected, they behave as if they were wired together.</p>
diff --git a/nodes/core/core/80-function.html b/nodes/core/core/80-function.html
index ca8090282..6e165473b 100644
--- a/nodes/core/core/80-function.html
+++ b/nodes/core/core/80-function.html
@@ -20,21 +20,15 @@
 </script>
 
 <script type="text/x-red" data-help-name="function">
-    <p>A function block where you can write code to do more interesting things.</p>
-    <p>The message is passed in as a JavaScript object called <code>msg</code>.</p>
+    <p>A JavaScript function block to run against the messages being received by the node.</p>
+    <p>The messages are passed in as a JavaScript object called <code>msg</code>.</p>
     <p>By convention it will have a <code>msg.payload</code> property containing
        the body of the message.</p>
-    <h4>Logging and Error Handling</h4>
-    <p>To log any information, or report an error, the following functions are available:</p>
-        <ul>
-            <li><code>node.log("Log message")</code></li>
-            <li><code>node.warn("Warning")</code></li>
-            <li><code>node.error("Error")</code></li>
-        </ul>
-    </p>
-    <p>The Catch node can also be used to handle errors. To invoke a Catch node,
-    pass <code>msg</code> as a second argument to <code>node.error</code>:</p>
-    <pre>node.error("Error",msg);</pre>
+    <p>The function is expected to return a message object (or multiple message objects), but can choose
+       to return nothing in order to halt a flow.</p>
+    <h3>Details</h3>
+    <p>See the <a target="_blank" href="http://nodered.org/docs/writing-functions.html">online documentation</a>
+    for more information on writing functions.</p>
     <h4>Sending messages</h4>
     <p>The function can either return the messages it wants to pass on to the next nodes
     in the flow, or can call <code>node.send(messages)</code>.</p>
@@ -47,7 +41,17 @@
           messages are sent to the corresponding output.</p>
     <p>If null is returned, either by itself or as an element of the array, no
           message is passed on.</p>
-    <p>See the <a target="_blank" href="http://nodered.org/docs/writing-functions.html">online documentation</a> for more help.</p>
+    <h4>Logging and Error Handling</h4>
+    <p>To log any information, or report an error, the following functions are available:</p>
+      <ul>
+          <li><code>node.log("Log message")</code></li>
+          <li><code>node.warn("Warning")</code></li>
+          <li><code>node.error("Error")</code></li>
+      </ul>
+    </p>
+    <p>The Catch node can also be used to handle errors. To invoke a Catch node,
+    pass <code>msg</code> as a second argument to <code>node.error</code>:</p>
+    <pre>node.error("Error",msg);</pre>
 </script>
 
 <script type="text/javascript">
diff --git a/nodes/core/logic/10-switch.html b/nodes/core/logic/10-switch.html
index 820b71359..a1a6b8d3a 100644
--- a/nodes/core/logic/10-switch.html
+++ b/nodes/core/logic/10-switch.html
@@ -36,11 +36,14 @@
 </script>
 
 <script type="text/x-red" data-help-name="switch">
-    <p>A node to route messages based on property values.</p>
-    <p>When a message arrives, the selected property is evaluated against each
-    of the defined rules. The message is then sent to the output of <i>all</i>
-    rules that pass.</p>
-    <p><b>Note</b>: the <i>otherwise</i> rule applies as a "not any of" the rules preceding it.</p>
+    <p>Route messages based on their property values.</p>
+    <h3>Details</h3>
+    <p>When a message arrives, the node will evaluate each of the defined rules
+    and forward the message to the corresponding outputs of any matching rules.</p>
+    <p>Optionally, the node can be set to stop evaluating rules once it finds one
+    that matches.</p>
+    <p>The rules can be evaluated against an individual message property, a flow or global
+    context property or the result of a JSONata expression.</p>
 </script>
 
 <script type="text/javascript">
diff --git a/nodes/core/logic/15-change.html b/nodes/core/logic/15-change.html
index ac11d0d07..f2f5c1edd 100644
--- a/nodes/core/logic/15-change.html
+++ b/nodes/core/logic/15-change.html
@@ -14,8 +14,8 @@
 
 <script type="text/x-red" data-help-name="change">
     <p>Set, change, delete or move properties of a message, flow context or global context.</p>
-    <p>The node can specify multiple rules that will be applied in turn.</p>
-    <h3>Options</h3>
+    <p>The node can specify multiple rules that will be applied in the order they are defined.</p>
+    <h3>Details</h3>
     <p>The available operations are:</p>
     <dl class="message-properties">
     <dt>Set</dt>
@@ -31,10 +31,8 @@
     <dt>Move</dt>
     <dd>move or rename a property.</dt>
     </dl>
-    <h3>Details</h3>
     <p>The "expression" type uses the <a href="http://jsonata.org/" target="_new">JSONata</a>
-    query and expression language. A tool is available to test expressions against
-    real data <a href="http://try.jsonata.org/" target="_new">here</a>.
+    query and expression language.
     </p>
 </script>