enhance puppet-strings documentation

3 files changed, 47 insertions, 114 deletions

diff --git a/README.md b/README.md
index 2668e95..7ccc141 100644
--- a/README.md
+++ b/README.md
@@ -95,119 +95,9 @@ with the FQDN of a box.
 
 ## Reference
 
-### Main class
-
-The main class has the following parameters:
-
-#### `manage_service`
-
-[Boolean] disable/enable the management of the ferm daemon
-
-#### `manage_configfile`
-
-[Boolean] disable/enable the management of the ferm default config
-
-#### `manage_initfile`
-
-[Boolean] disable/enable the management of the ferm init script for RedHat-based OS
-
-#### `configfile`
-
-[Stdlib::Absolutepath] path to the config file
-
-#### `forward_policy`
-
-[Ferm::Policies] default policy for the FORWARD chain
-
-#### `output_policy`
-
-[Ferm::Policies] default policy for the OUTPUT chain
-
-#### `input_policy`
-
-[Ferm::Policies] default policy for the INPUT chain
-
-#### `rules`
-
-A hash that holds all data for ferm::rule
-
-### rule defined resource
-
-This creates an entry in the correct chain file for ferm.
-
-#### `chain`
-
-The chain where we place this rule
-
-#### `policy`
-
-The desired policy. Allowed values are Enum['ACCEPT','DROP', 'REJECT']
-
-#### `protocol`
-
-the protocol we would like to filter. Allowed values are Enum['icmp', 'tcp', 'udp']
-
-### `proto_options`
-
-The protocol options we would like to add.
-The following example will suppress the hostname in programs like `traceroute`:
-
-```yaml
----
-ferm::rules:
-  'drop_output_traceroute':
-    chain: 'OUTPUT'
-    policy: 'DROP'
-    proto: 'icmp'
-    proto_options: 'icmp-type time-exceeded'
-```
-
-#### `comment`
-
-A comment that will be written into the file and into ip(6)tables
-
-#### `dport`
-
-The destination port we want to filter for. Can be any string from
-/etc/services or an integer
-
-#### `sport`
-
-Like the destination port above, just for the source port
-
-#### `saddr`
-
-Source IPv4/IPv6 address. Can be one or many of them. Multiple addresses are
-always encapsulated in braces:
-'(127.0.0.1 2003::)'
-
-IPv4 and IPv6 addresses can be mixed. CIDR notation is possible if you want to
-block networks, otherwise /32 or /128 is assumed by ferm/ip(6)tables
-
-#### `daddr`
-
-Same as above, just for the destination IP address
-
-#### `ensure`
-
-Add or remove it from the ruleset
-
-#### `interface`
-
-If set, this rule only applies to this specific interface
-
-### chain defined resource
-
-The module defines the three default chains for you, INPUT, FORWARD and OUTPUT.
-You're able to define own chains if you want to
-
-#### `policy`
-
-The desired default policy for the chain
-
-#### `chain`
-
-The name of the chain
+All parameters are documented within the classes. We generate markdown
+documentation. It's available in the [REFERENCE.md](REFERENCE.md). It also
+contains many examples.
 
 ## Development
 
@@ -220,6 +110,10 @@ bundle install --path .vendor/ --without system_tests --without development --wi
 bundle exec rake test
 ```
 
+For more details about the development workflow and on how to contribute,
+please check the [CONTRIBUTING.md](.github/CONTRIBUTING.md).
+
 ## Authors
 
-puppet-ferm is maintained by [Vox Pupuli](https://voxpupuli.org), it was written by [Tim 'bastelfreak' Meusel](https://github.com/bastelfreak).
+puppet-ferm is maintained by [Vox Pupuli](https://voxpupuli.org), it was written
+by [Tim 'bastelfreak' Meusel](https://github.com/bastelfreak).
diff --git a/REFERENCE.md b/REFERENCE.md
index 62a5d3b..3225969 100644
--- a/REFERENCE.md
+++ b/REFERENCE.md
@@ -292,6 +292,28 @@ ferm::rule{'allow-ssh-localhost':
 }
 ```
 
+##### Confuse people that do a traceroute/mtr/ping to your system
+
+```puppet
+ferm::rule{'drop-icmp-time-exceeded':
+  chain         => 'OUTPUT',
+  policy        => 'DROP',
+  proto         => 'icmp',
+  proto_options => 'icmp-type time-exceeded',
+}
+```
+
+##### allow multiple protocols
+
+```puppet
+ferm::rule{'allow_consul':
+  chain  => 'INPUT',
+  policy => 'ACCEPT',
+  proto  => ['udp', 'tcp'],
+  dport  => 8301,
+}
+```
+
 #### Parameters
 
 The following parameters are available in the `ferm::rule` defined type.
diff --git a/manifests/rule.pp b/manifests/rule.pp
index a973601..1acbfd1 100644
--- a/manifests/rule.pp
+++ b/manifests/rule.pp
@@ -17,6 +17,23 @@
 #     saddr  => '127.0.0.1',
 #   }
 #
+#
+# @example Confuse people that do a traceroute/mtr/ping to your system
+#   ferm::rule{'drop-icmp-time-exceeded':
+#     chain         => 'OUTPUT',
+#     policy        => 'DROP',
+#     proto         => 'icmp',
+#     proto_options => 'icmp-type time-exceeded',
+#   }
+#
+# @example allow multiple protocols
+#   ferm::rule{'allow_consul':
+#     chain  => 'INPUT',
+#     policy => 'ACCEPT',
+#     proto  => ['udp', 'tcp'],
+#     dport  => 8301,
+#   }
+#
 # @param chain Configure the chain where we want to add the rule
 # @param proto Which protocol do we want to match, typically UDP or TCP
 # @param comment A comment that will be added to the ferm config and to ip{,6}tables