From 479b18354d56f214d1f17679ebba99ec4500c7b8 Mon Sep 17 00:00:00 2001
From: Nick O'Leary <nick.oleary@gmail.com>
Date: Wed, 24 May 2017 16:55:53 +0100
Subject: [PATCH] More core node info help tidy up

---
 nodes/core/core/20-inject.html         |  2 +-
 nodes/core/io/21-httpin.html           | 88 +++++++++++++++-----------
 nodes/core/io/21-httprequest.html      | 49 ++++++++------
 nodes/core/locales/en-US/messages.json |  2 +-
 nodes/core/storage/50-file.html        | 42 ++++++------
 5 files changed, 106 insertions(+), 77 deletions(-)

diff --git a/nodes/core/core/20-inject.html b/nodes/core/core/20-inject.html
index 5e149a273..c5654f490 100644
--- a/nodes/core/core/20-inject.html
+++ b/nodes/core/core/20-inject.html
@@ -157,7 +157,7 @@ payload can be a variety of types, including strings, JavaScript objects or the
     <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>
+    <dd>An optional property that can be configured in the node.</dd>
 </dl>
 <h3>Details</h3>
 <p>The Inject node can initiate a flow with a specific payload value.
diff --git a/nodes/core/io/21-httpin.html b/nodes/core/io/21-httpin.html
index a4cac1f9f..680e4fa00 100644
--- a/nodes/core/io/21-httpin.html
+++ b/nodes/core/io/21-httpin.html
@@ -46,32 +46,43 @@
 </script>
 
 <script type="text/x-red" data-help-name="http in">
-    <p>Provides an input node for http requests, allowing the creation of simple web services.</p>
-    <p>The resulting message has the following properties:
-        <ul>
-            <li>msg.req : <a href="http://expressjs.com/api.html#req">http request</a></li>
-            <li>msg.res : <a href="http://expressjs.com/api.html#res">http response</a></li>
-        </ul>
-    </p>
-    <p>For POST/PUT requests, the body is available under <code>msg.req.body</code>. This
-       uses the <a href="http://expressjs.com/api.html#bodyParser">Express bodyParser middleware</a> to parse the content to a JSON object.
-    </p>
-    <p>
-       By default, this expects the body of the request to be url encoded:
-       <pre>foo=bar&amp;this=that</pre>
-    </p>
-    <p>
-       To send JSON encoded data to the node, the content-type header of the request must be set to
-       <code>application/json</code>.
-    </p>
-    <p>
-       If file uploads are enabled for POST requests, the files will be available under
-       <code>msg.req.files</code>.
-    <p>
-       <b>Note: </b>This node does not send any response to the http request.
-       This should be done with a subsequent HTTP Response node.
-    </p>
-
+    <p>Creates an HTTP end-point for creating web services.</p>
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload</dt>
+        <dd>For a GET request, contains an object of any query string parameters.
+            Otherwise, contains the body of the HTTP request.</dd>
+        <dt>req<span class="property-type">object</span></dt>
+        <dd>An HTTP request object. This object contains multiple properties that
+            provide information about the request.
+            <ul>
+             <li><code>body</code> - the body of the incoming request. The format
+                 will depend on the request.</li>
+             <li><code>headers</code> - an object containing the HTTP request headers.</li>
+             <li><code>query</code> - an object containing any query string parameters.</li>
+             <li><code>params</code> - an object containing any route parameters.</li>
+             <li><code>cookies</code> - an object containing the cookies for the request.</li>
+             <li><code>files</code> - if enabled with the node, an object containing
+                 any files uploaded as part of a POST request.</li>
+            </ul>
+        </dd>
+        <dt>res<span class="property-type">object</span></dt>
+        <dd>An HTTP response object. This property should not be used directly;
+            the <code>HTTP Response</code> node documents how to respond to a request.
+            This property must remain attached to the message passed to the response node.</dd>
+    </dl>
+    <h3>Details</h3>
+    <p>The node will listen on the configured path for requests of a particular type.
+       The path can be fully specified, such as <code>/user</code>, or include
+       named parameters that accept any value, such as <code>/user/:name</code>.
+       When named parameters are used, their actual value in a request can be accessed under `msg.req.params`.</p>
+    <p>For requests that include a body, such as a POST or PUT, the contents of
+       the request is made available as <code>msg.payload</code>.</p>
+    <p>If the content type of the request can be determined, the body will be parsed to
+       any appropriate type. For example, <code>application/json</code> will be parsed to
+       its JavaScript object representation.</p>
+    <p><b>Note:</b> this node does not send any response to the request. The flow
+       must include an HTTP Response node to complete the request.</p>
 </script>
 
 <script type="text/x-red" data-template-name="http response">
@@ -93,19 +104,24 @@
 </script>
 
 <script type="text/x-red" data-help-name="http response">
-    <p>Sends responses back to http requests received from an HTTP Input node.</p>
-    <p>The response can be customised using the following message properties:</p>
-    <ul>
-        <li><code>payload</code> is sent as the body of the response</li>
-        <li><code>statusCode</code>, if set, is used as the response status code (default: 200)</li>
-        <li><code>headers</code>, if set, should be an object containing field/value
-        pairs to be added as response headers.</li>
-        <li><code>cookies</code>, if set, can be used to set or delete cookies.
-    </ul>
+    <p>Sends responses back to requests received from an HTTP Input node.</p>
+
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">string</span></dt>
+        <dd>The body of the response.</dd>
+        <dt class="optional">statusCode <span class="property-type">number</span></dt>
+        <dd>If set, this is used as the response status code. Default: 200.</dd>
+        <dt class="optional">headers <span class="property-type">object</span></dt>
+        <dd>If set, provides HTTP headers to include in the response.</dd>
+        <dt class="optional">cookies <span class="property-type">object</span></dt>
+        <dd>If set, can be used to set or delete cookies.</dd>
+    </dl>
+    <h3>Details</h3>
     <p>The <code>statusCode</code> and <code>headers</code> can also be set within
     the node itself. If a property is set within the node, it cannot be overridden
     by the corresponding message property.</p>
-    <h3>Cookie handling</h3>
+    <h4>Cookie handling</h4>
     <p>The <code>cookies</code> property must be an object of name/value pairs.
     The value can be either a string to set the value of the cookie with default
     options, or it can be an object of options.<p>
diff --git a/nodes/core/io/21-httprequest.html b/nodes/core/io/21-httprequest.html
index 36f8900ed..bd157a9ff 100644
--- a/nodes/core/io/21-httprequest.html
+++ b/nodes/core/io/21-httprequest.html
@@ -70,29 +70,40 @@
 </script>
 
 <script type="text/x-red" data-help-name="http request">
-    <p>Provides a node for making http requests.</p>
-    <p>The URL and HTTP method can be configured in the node, if they are left blank they should be set in an incoming message on <code>msg.url</code> and <code>msg.method</code>:</p>
-    <ul>
-        <li><code>url</code>, if set, is used as the url of the request. Must start with http: or https:</li>
-        <li><code>method</code>, if set, is used as the HTTP method of the request.
-        Must be one of <code>GET</code>, <code>PUT</code>, <code>POST</code>, <code>PATCH</code> or <code>DELETE</code> (default: GET)</li>
-        <li><code>headers</code>, if set, should be an object containing field/value
-        pairs to be added as request headers</li>
-        <li><code>payload</code> is sent as the body of the request</li>
-    </ul>
+    <p>Sends HTTP requests and returns the response.</p>
+
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt class="optional">url <span class="property-type">string</span></dt>
+        <dd>If not configured in the node, this optional property sets the url of the request.</dd>
+        <dt class="optional">method <span class="property-type">string</span></dt>
+        <dd>If not configured in the node, this optional property sets the HTTP method of the request.
+            Must be one of <code>GET</code>, <code>PUT</code>, <code>POST</code>, <code>PATCH</code> or <code>DELETE</code>.</dd>
+        <dt class="optional">headers <span class="property-type">object</span></dt>
+        <dd>Sets the HTTP headers of the request.</dd>
+        <dt class="optional">payload</dt>
+        <dd>Sent as the body of the request.</dd>
+    </dl>
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">string | object | buffer</span></dt>
+        <dd>The body of the response. The node can be configured to return the body
+             as a string, attempt to parse it as a JSON string or leave it as a
+             binary buffer.</dd>
+        <dt>statusCode <span class="property-type">number</span></dt>
+        <dd>The status code of the response, or the error code if the request could not be completed.</dd>
+        <dt>headers <span class="property-type">object</span></dt>
+        <dd>An object containing the response headers.</dd>
+        <dt>responseUrl <span class="property-type">string</span></dt>
+        <dd>In case any redirects occurred while processing the request, this property is the final redirected url.
+            Otherwise, the url of the original request.</dd>
+    </dl>
+    <h3>Details</h3>
     <p>When configured within the node, the URL property can contain <a href="http://mustache.github.io/mustache.5.html" target="_blank">mustache-style</a> tags. These allow the
     url to be constructed using values of the incoming message. For example, if the url is set to
     <code>example.com/{{{topic}}}</code>, it will have the value of <code>msg.topic</code> automatically inserted.
     Using {{{...}}} prevents mustache from escaping characters like / & etc.</p>
-    <p>
-    The output message contains the following properties:
-    <ul>
-        <li><code>payload</code> is the body of the response</li>
-        <li><code>statusCode</code> is the status code of the response, or the error code if the request could not be completed</li>
-        <li><code>headers</code> is an object containing the response headers</li>
-        <li><code>responseUrl</code> is the url of the server that responds</li>
-    </ul>
-    <p><b>Note</b>: If you need to configure a proxy please add <b>http_proxy=...</b> to your environment variables and restart Node-RED.</p>
+    <p><b>Note</b>: If running behind a proxy, the standard <code>http_proxy=...</code> environment variable should be set and Node-RED restarted.</p>
 </script>
 
 <script type="text/javascript">
diff --git a/nodes/core/locales/en-US/messages.json b/nodes/core/locales/en-US/messages.json
index f5b9867e7..21570855a 100644
--- a/nodes/core/locales/en-US/messages.json
+++ b/nodes/core/locales/en-US/messages.json
@@ -782,6 +782,6 @@
             "appendfail": "failed to append to file: __error__",
             "createfail": "failed to create file: __error__"
         },
-        "tip": "Tip: You should fully path the Filename."
+        "tip": "Tip: The filename should be an absolute path, otherwise it will be relative to the working directory of the Node-RED process."
     }
 }
diff --git a/nodes/core/storage/50-file.html b/nodes/core/storage/50-file.html
index 6b83e01ca..964823286 100644
--- a/nodes/core/storage/50-file.html
+++ b/nodes/core/storage/50-file.html
@@ -6,18 +6,18 @@
     </div>
     <div class="form-row">
         <label for="node-input-overwriteFile"><i class="fa fa-random"></i> <span data-i18n="file.label.action"></span></label>
-        <select type="text" id="node-input-overwriteFile" style="display: inline-block; width: 250px; vertical-align: top;">
+        <select type="text" id="node-input-overwriteFile" style="width: 250px;">
             <option value="false" data-i18n="file.action.append"></option>
             <option value="true" data-i18n="file.action.overwrite"></option>
             <option value="delete" data-i18n="file.action.delete"></option>
         </select>
     </div>
-    <div class="form-row" id="node-appline">
+    <div class="form-row form-row-file-write-options">
         <label>&nbsp;</label>
         <input type="checkbox" id="node-input-appendNewline" style="display: inline-block; width: auto; vertical-align: top;">
         <label for="node-input-appendNewline" style="width: 70%;"><span data-i18n="file.label.addnewline"></span></label>
     </div>
-    <div class="form-row">
+    <div class="form-row form-row-file-write-options">
         <label>&nbsp;</label>
         <input type="checkbox" id="node-input-createDir" style="display: inline-block; width: auto; vertical-align: top;">
         <label for="node-input-createDir" style="width: 70%;"><span data-i18n="file.label.createdir"></span></label>
@@ -30,18 +30,20 @@
 </script>
 
 <script type="text/x-red" data-help-name="file">
-    <p>Writes <code>msg.payload</code> to the file specified, for example to create a log.</p>
+    <p>Writes <code>msg.payload</code> to a file, either adding to the end or replacing the existing content.
+       Alternatively, it can delete the file.</p>
     <h3>Inputs</h3>
     <dl class="message-properties">
         <dt class="optional">filename <span class="property-type">string</span></dt>
-        <dd>If not configured in the node the filename can be set using the filename property.</dd>
+        <dd>If not configured in the node, this optional property sets the name of the file to be updated.</dd>
     </dl>
     <h3>Details</h3>
-    <p>By default a newline is added to every message. This can be turned off if required, for example,
-    to allow binary files to be written.</p>
-    <p>The default behaviour is to append to the file. This can be changed to overwrite the file
-    each time, for example if you want to output a "static" web page or report.</p>
-    <p>This node can also be configured to delete a file if required.</p>
+    <p>Each message payload will be added to the end of the file, optionally appending
+    a newline (\n) character between each one.</p>
+    <p>It can be configured to overwrite the entire file rather than append. For example,
+    when writing binary data to a file, such as an image, this option should be used
+    and the option to append a newline should be disabled.</p>
+    <p>Alternatively, this node can be configured to delete the file.</p>
 </script>
 
 <script type="text/x-red" data-template-name="file in">
@@ -64,23 +66,23 @@
 </script>
 
 <script type="text/x-red" data-help-name="file in">
-    <p>Reads the specified file and sends the content as <code>msg.payload</code>,
-    and the filename as <code>msg.filename</code>.</p>
+    <p>Reads the contents of a file as either a string or binary buffer.</p>
     <h3>Inputs</h3>
     <dl class="message-properties">
         <dt class="optional">filename <span class="property-type">string</span></dt>
-        <dd>if not set in the node configuration the filename to read can be passed in.</dd>
+        <dd>if not set in the node configuration, this property sets the filename to read.</dd>
     </dl>
     <h3>Outputs</h3>
     <dl class="message-properties">
         <dt>payload <span class="property-type">string | buffer</span></dt>
-        <dd>the contents of the file as either a string or binary buffer.</dd>
-        <dt>filename <span class="property-type">string</span></dt>
-        <dd>the filename of the read file.</dd>
+        <dd>The contents of the file as either a string or binary buffer.</dd>
+        <dt class="optional">filename <span class="property-type">string</span></dt>
+        <dd>If not configured in the node, this optional property sets the name of the file to be read.</dd>
     </dl>
     <h3>Details</h3>
-    <p>It is advisable to fully specify the required file path and name.
-    On Windows you may need to use \\ to specify the path separator.</p>
+    <p>The filename should be an absolute path, otherwise it will be relative to
+    the working directory of the Node-RED process.</p>
+    <p>On Windows, path separators may need to be escaped, for example: <code>\\Users\\myUser</code>.</p>
 </script>
 
 <script type="text/javascript">
@@ -110,8 +112,8 @@
         },
         oneditprepare: function() {
             $("#node-input-overwriteFile").on("change",function() {
-                if (this.value === "delete") { $("#node-appline").hide(); }
-                else { $("#node-appline").show(); }
+                if (this.value === "delete") { $(".form-row-file-write-options").hide(); }
+                else { $(".form-row-file-write-options").show(); }
             });
         }
     });