(MODULES-8183) Fix ToC truncation in REFERENCE.md

Puppet Strings prefers a `@summary` tag with a max of 140 characters to
fill in the Table of Contents summary. Without this, the description
will appear truncated.

Add `@summary` and `@example` tags to the type documentation.

2 files changed, 117 insertions, 93 deletions

diff --git a/REFERENCE.md b/REFERENCE.md
index 5304160..8019100 100644
--- a/REFERENCE.md
+++ b/REFERENCE.md
@@ -1,42 +1,48 @@
 # Reference
+
 <!-- DO NOT EDIT: This document was generated by Puppet Strings -->
 
 ## Table of Contents
 
-**Resource types**
+### Resource types
 
-* [`augeas`](#augeas): Apply a change or an array of changes to the filesystem using the augeas tool.  Requires:  - [Augeas](http://www.augeas.net) - The ruby-augea
+* [`augeas`](#augeas): Apply a change or an array of changes to the filesystem using the augeas tool.
 
 ## Resource types
 
-### augeas
-
-Apply a change or an array of changes to the filesystem
-using the augeas tool.
+### <a name="augeas"></a>`augeas`
 
 Requires:
 
 - [Augeas](http://www.augeas.net)
 - The ruby-augeas bindings
 
-Sample usage with a string:
+#### Examples
+
+##### Sample usage with a string:
 
-    augeas{"test1" :
-      context => "/files/etc/sysconfig/firstboot",
-      changes => "set RUN_FIRSTBOOT YES",
-      onlyif  => "match other_value size > 0",
-    }
+```puppet
 
-Sample usage with an array and custom lenses:
+augeas { "test1":
+  context => "/files/etc/sysconfig/firstboot",
+  changes => "set RUN_FIRSTBOOT YES",
+  onlyif  => "match other_value size > 0",
+}
+```
 
-    augeas{"jboss_conf":
-      context   => "/files",
-      changes   => [
-          "set etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress",
-          "set etc/jbossas/jbossas.conf/JAVA_HOME /usr",
-        ],
-      load_path => "$/usr/share/jbossas/lenses",
-    }
+##### Sample usage with an array and custom lenses:
+
+```puppet
+
+augeas { "jboss_conf":
+  context   => "/files",
+  changes   => [
+      "set etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress",
+      "set etc/jbossas/jbossas.conf/JAVA_HOME /usr",
+    ],
+  load_path => "$/usr/share/jbossas/lenses",
+}
+```
 
 #### Properties
 
@@ -46,27 +52,88 @@ The following properties are available in the `augeas` type.
 
 The expected return code from the augeas command. Should not be set.
 
-Default value: 0
+Default value: `0`
 
 #### Parameters
 
 The following parameters are available in the `augeas` type.
 
-##### `name`
+* [`changes`](#changes)
+* [`context`](#context)
+* [`force`](#force)
+* [`incl`](#incl)
+* [`lens`](#lens)
+* [`load_path`](#load_path)
+* [`name`](#name)
+* [`onlyif`](#onlyif)
+* [`provider`](#provider)
+* [`root`](#root)
+* [`show_diff`](#show_diff)
+* [`type_check`](#type_check)
+
+##### <a name="changes"></a>`changes`
 
-namevar
+The changes which should be applied to the filesystem. This
+can be a command or an array of commands. The following commands are supported:
 
-The name of this task. Used for uniqueness.
+* `set <PATH> <VALUE>` --- Sets the value `VALUE` at location `PATH`
+* `setm <PATH> <SUB> <VALUE>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `VALUE`
+* `rm <PATH>` --- Removes the node at location `PATH`
+* `remove <PATH>` --- Synonym for `rm`
+* `clear <PATH>` --- Sets the node at `PATH` to `NULL`, creating it if needed
+* `clearm <PATH> <SUB>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `NULL`
+* `touch <PATH>` --- Creates `PATH` with the value `NULL` if it does not exist
+* `ins <LABEL> (before|after) <PATH>` --- Inserts an empty node `LABEL` either before or after `PATH`.
+* `insert <LABEL> <WHERE> <PATH>` --- Synonym for `ins`
+* `mv <PATH> <OTHER PATH>` --- Moves a node at `PATH` to the new location `OTHER PATH`
+* `move <PATH> <OTHER PATH>` --- Synonym for `mv`
+* `rename <PATH> <LABEL>` --- Rename a node at `PATH` to a new `LABEL`
+* `defvar <NAME> <PATH>` --- Sets Augeas variable `$NAME` to `PATH`
+* `defnode <NAME> <PATH> <VALUE>` --- Sets Augeas variable `$NAME` to `PATH`, creating it with `VALUE` if needed
+
+If the `context` parameter is set, that value is prepended to any relative `PATH`s.
 
-##### `context`
+##### <a name="context"></a>`context`
 
 Optional context path. This value is prepended to the paths of all
 changes if the path is relative. If the `incl` parameter is set,
 defaults to `/files + incl`; otherwise, defaults to the empty string.
 
-Default value: ''
+Default value: `''`
+
+##### <a name="force"></a>`force`
+
+Optional command to force the augeas type to execute even if it thinks changes
+will not be made. This does not override the `onlyif` parameter.
+
+Default value: ``false``
+
+##### <a name="incl"></a>`incl`
+
+Load only a specific file, such as `/etc/hosts`. This can greatly speed
+up the execution the resource. When this parameter is set, you must also
+set the `lens` parameter to indicate which lens to use.
+
+##### <a name="lens"></a>`lens`
+
+Use a specific lens, such as `Hosts.lns`. When this parameter is set, you
+must also set the `incl` parameter to indicate which file to load.
+The Augeas documentation includes [a list of available lenses](http://augeas.net/stock_lenses.html).
+
+##### <a name="load_path"></a>`load_path`
+
+Optional colon-separated list or array of directories; these directories are searched for schema definitions.
+The agent's `$libdir/augeas/lenses` path will always be added to support pluginsync.
+
+Default value: `''`
+
+##### <a name="name"></a>`name`
+
+namevar
+
+The name of this task. Used for uniqueness.
 
-##### `onlyif`
+##### <a name="onlyif"></a>`onlyif`
 
 Optional augeas command and comparisons to control the execution of this type.
 
@@ -95,72 +162,22 @@ where:
 * `INT` is a number
 * `AN_ARRAY` is in the form `['a string', 'another']`
 
-Default value: ''
+Default value: `''`
 
-##### `changes`
+##### <a name="provider"></a>`provider`
 
-The changes which should be applied to the filesystem. This
-can be a command or an array of commands. The following commands are supported:
-
-* `set <PATH> <VALUE>` --- Sets the value `VALUE` at location `PATH`
-* `setm <PATH> <SUB> <VALUE>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `VALUE`
-* `rm <PATH>` --- Removes the node at location `PATH`
-* `remove <PATH>` --- Synonym for `rm`
-* `clear <PATH>` --- Sets the node at `PATH` to `NULL`, creating it if needed
-* `clearm <PATH> <SUB>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `NULL`
-* `touch <PATH>` --- Creates `PATH` with the value `NULL` if it does not exist
-* `ins <LABEL> (before|after) <PATH>` --- Inserts an empty node `LABEL` either before or after `PATH`.
-* `insert <LABEL> <WHERE> <PATH>` --- Synonym for `ins`
-* `mv <PATH> <OTHER PATH>` --- Moves a node at `PATH` to the new location `OTHER PATH`
-* `move <PATH> <OTHER PATH>` --- Synonym for `mv`
-* `rename <PATH> <LABEL>` --- Rename a node at `PATH` to a new `LABEL`
-* `defvar <NAME> <PATH>` --- Sets Augeas variable `$NAME` to `PATH`
-* `defnode <NAME> <PATH> <VALUE>` --- Sets Augeas variable `$NAME` to `PATH`, creating it with `VALUE` if needed
-
-If the `context` parameter is set, that value is prepended to any relative `PATH`s.
+The specific backend to use for this `augeas` resource. You will seldom need to specify this --- Puppet will usually
+discover the appropriate provider for your platform.
 
-##### `root`
+##### <a name="root"></a>`root`
 
 A file system path; all files loaded by Augeas are loaded underneath `root`.
 
-Default value: /
-
-##### `load_path`
-
-Optional colon-separated list or array of directories; these directories are searched for schema definitions. The agent's `$libdir/augeas/lenses` path will always be added to support pluginsync.
+Default value: `/`
 
-Default value: ''
+##### <a name="show_diff"></a>`show_diff`
 
-##### `force`
-
-Optional command to force the augeas type to execute even if it thinks changes
-will not be made. This does not override the `onlyif` parameter.
-
-Default value: `false`
-
-##### `type_check`
-
-Valid values: `true`, `false`
-
-Whether augeas should perform typechecking. Defaults to false.
-
-Default value: `false`
-
-##### `lens`
-
-Use a specific lens, such as `Hosts.lns`. When this parameter is set, you
-must also set the `incl` parameter to indicate which file to load.
-The Augeas documentation includes [a list of available lenses](http://augeas.net/stock_lenses.html).
-
-##### `incl`
-
-Load only a specific file, such as `/etc/hosts`. This can greatly speed
-up the execution the resource. When this parameter is set, you must also
-set the `lens` parameter to indicate which lens to use.
-
-##### `show_diff`
-
-Valid values: `true`, `false`, yes, no
+Valid values: ``true``, ``false``, `yes`, `no`
 
 Whether to display differences when the file changes, defaulting to
 true.  This parameter is useful for files that may contain passwords or
@@ -168,5 +185,13 @@ other secret data, which might otherwise be included in Puppet reports or
 other insecure outputs.  If the global `show_diff` setting
 is false, then no diffs will be shown even if this parameter is true.
 
-Default value: `true`
+Default value: ``true``
+
+##### <a name="type_check"></a>`type_check`
+
+Valid values: ``true``, ``false``
+
+Whether augeas should perform typechecking. Defaults to false.
+
+Default value: ``false``
 
diff --git a/lib/puppet/type/augeas.rb b/lib/puppet/type/augeas.rb
index 2303fdc..ef93bce 100644
--- a/lib/puppet/type/augeas.rb
+++ b/lib/puppet/type/augeas.rb
@@ -23,25 +23,24 @@ Puppet::Type.newtype(:augeas) do
   feature :execute_changes, 'Actually make the changes'
 
   @doc = <<-'EOT'
-    Apply a change or an array of changes to the filesystem
-    using the augeas tool.
+    @summary Apply a change or an array of changes to the filesystem using the augeas tool.
 
     Requires:
 
     - [Augeas](http://www.augeas.net)
     - The ruby-augeas bindings
 
-    Sample usage with a string:
+    @example Sample usage with a string:
 
-        augeas{"test1" :
+        augeas { "test1":
           context => "/files/etc/sysconfig/firstboot",
           changes => "set RUN_FIRSTBOOT YES",
           onlyif  => "match other_value size > 0",
         }
 
-    Sample usage with an array and custom lenses:
+    @example Sample usage with an array and custom lenses:
 
-        augeas{"jboss_conf":
+        augeas { "jboss_conf":
           context   => "/files",
           changes   => [
               "set etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress",