From 35d18d3fd725a9fbe2b51b1f15dcd847d3d5c2b4 Mon Sep 17 00:00:00 2001
From: Daniel Nelson <daniel.nelson@influxdb.com>
Date: Wed, 23 Jan 2019 17:26:50 -0800
Subject: [PATCH] Update multifile plugin docs

---
 CHANGELOG.md                       |  1 +
 README.md                          |  1 +
 plugins/inputs/multifile/README.md | 35 +++++++++++++++++++-----------
 3 files changed, 24 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 125326adf..fa85eda7a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
 - [cloud_pubsub](/plugins/inputs/cloud_pubsub/README.md) - Contributed by @emilymye
 - [neptune_apex](/plugins/inputs/neptune_apex/README.md) - Contributed by @MaxRenaud
 - [nginx_upstream_check](/plugins/inputs/nginx_upstream_check/README.md) - Contributed by @dmitryilyin
+- [multifile](/plugins/inputs/multifile/README.md) - Contributed by @martin2250
 
 #### New Outputs
 
diff --git a/README.md b/README.md
index 2177be4cb..74dbc8ae5 100644
--- a/README.md
+++ b/README.md
@@ -206,6 +206,7 @@ For documentation on the latest development code see the [documentation index][d
 * [minecraft](./plugins/inputs/minecraft)
 * [mongodb](./plugins/inputs/mongodb)
 * [mqtt_consumer](./plugins/inputs/mqtt_consumer)
+* [multifile](./plugins/inputs/multifile)
 * [mysql](./plugins/inputs/mysql)
 * [nats_consumer](./plugins/inputs/nats_consumer)
 * [nats](./plugins/inputs/nats)
diff --git a/plugins/inputs/multifile/README.md b/plugins/inputs/multifile/README.md
index 2178f0dbd..558d4e442 100644
--- a/plugins/inputs/multifile/README.md
+++ b/plugins/inputs/multifile/README.md
@@ -1,16 +1,20 @@
 # Multifile Input Plugin
 
-### Description
-The multifile input plugin allows telegraf to gather data from multiple files into a single point, creating one field or tag per file.
+The multifile input plugin allows Telegraf to combine data from multiple files
+into a single metric, creating one field or tag per file.  This is often
+useful creating custom metrics from the `/sys` or `/proc` filesystems.
+
+> Note: If you wish to parse metrics from a single file formatted in one of the supported
+> [input data formats][], you should use the [file][] input plugin instead.
 
 ### Configuration
-```
+```toml
 [[inputs.multifile]]
   ## Base directory where telegraf will look for files.
   ## Omit this option to use absolute paths.
   base_dir = "/sys/bus/i2c/devices/1-0076/iio:device0"
 
-  ## If true, Telegraf discard all data when a single file can't be read.
+  ## If true discard all data when a single file can't be read.
   ## Else, Telegraf omits the field generated from this file.
   # fail_early = true
 
@@ -28,18 +32,20 @@ The multifile input plugin allows telegraf to gather data from multiple files in
     dest = "humidityrelative"
     conversion = "float(3)"
 ```
-* `file.file`:
-Path of the file to be parsed
-* `file.dest`:
-Name of the field/tag created, defaults to `$(basename file)`
-* `file.conversion`:
-Data format used to parse the file contents
+
+Each file table can contain the following options:
+* `file`:
+Path of the file to be parsed, relative to the `base_dir`.
+* `dest`:
+Name of the field/tag key, defaults to `$(basename file)`.
+* `conversion`:
+Data format used to parse the file contents:
 	* `float(X)`: Converts the input value into a float and divides by the Xth power of 10. Efficively just moves the decimal left X places. For example a value of `123` with `float(2)` will result in `1.23`.
 	* `float`: Converts the value into a float with no adjustment. Same as `float(0)`.
 	* `int`: Convertes the value into an integer.
-	* `string`, `""`: No conversion
-	* `bool`: Convertes the value into a boolean
-	* `tag`: File content is used as a tag
+	* `string`, `""`: No conversion.
+	* `bool`: Convertes the value into a boolean.
+	* `tag`: File content is used as a tag.
 
 ### Example Output
 This example shows a BME280 connected to a Raspberry Pi, using the sample config.
@@ -57,3 +63,6 @@ The kernel driver provides the following files in `/sys/bus/i2c/devices/1-0076/i
 * `in_humidityrelative_input`: `48900`
 * `in_pressure_input`: `101.343285156`
 * `in_temp_input`: `20400`
+
+[input data formats]: /docs/DATA_FORMATS_INPUT.md
+[file]: /plugins/inputs/file/README.md