Merge pull request #6 from kenyon/alphabetize-docs

Alphabetize and fix generation of docs

Author: kenyon

REFERENCE.md

@@ -18,7 +18,7 @@
 
 ### Defined types
 
-* [`bind::key`](#bindkey)
+* [`bind::key`](#bindkey): Create TSIG key for zone updates in the configuration file for BIND
 * [`bind::zone`](#bindzone): A DNS zone
 
 ### Resource types
@@ -77,6 +77,7 @@ The following parameters are available in the `bind` class:
 * [`doc_packages_ensure`](#doc_packages_ensure)
 * [`utils_packages_ensure`](#utils_packages_ensure)
 * [`logging`](#logging)
+* [`keys`](#keys)
 * [`options`](#options)
 * [`package_manage`](#package_manage)
 * [`service_manage`](#service_manage)
@@ -102,7 +103,6 @@ The following parameters are available in the `bind` class:
 * [`zone_default_rname`](#zone_default_rname)
 * [`zone_default_serial`](#zone_default_serial)
 * [`zone_default_ttl`](#zone_default_ttl)
-* [`keys`](#keys)
 
 ##### <a name="authoritative"></a>`authoritative`
 
@@ -209,6 +209,14 @@ statement](https://bind9.readthedocs.io/en/latest/reference.html#logging-stateme
 
 Default value: ``undef``
 
+##### <a name="keys"></a>`keys`
+
+Data type: `Hash`
+
+Hash for creating Bind::Key resources.
+
+Default value: `{}`
+
 ##### <a name="options"></a>`options`
 
 Data type: `Optional[Bind::Options]`
@@ -434,19 +442,25 @@ in the `$zones` parameter. Also, individual resource records can override this v
 
 Default value: `'2d'`
 
-##### <a name="keys"></a>`keys`
+## Defined types
 
-Data type: `Hash`
+### <a name="bindkey"></a>`bind::key`
 
-Hash for creating Bind::Key resources.
+Create TSIG key for zone updates in the configuration file for BIND
 
-Default value: `{}`
+* **See also**
+  * https://bind9.readthedocs.io/en/latest/advanced.html#tsig
 
-## Defined types
+#### Examples
 
-### <a name="bindkey"></a>`bind::key`
+##### Add a TSIG key to the nameserver
 
-The bind::key class.
+```puppet
+bind::key { 'tsig-client':
+  algorithm => 'hmac-sha512',
+  secret    => 'secret-key-data',
+}
+```
 
 #### Parameters
 
@@ -459,13 +473,15 @@ The following parameters are available in the `bind::key` defined type:
 
 Data type: `Enum['hmac-sha256', 'hmac-sha384', 'hmac-sha512']`
 
-
+Defines the algorithm which was used to generate the key data.
+For security reasons just allow algorithms hmac-sha256 and above:
+https://www.rfc-editor.org/rfc/rfc8945.html#name-algorithms-and-identifiers
 
 ##### <a name="secret"></a>`secret`
 
 Data type: `String[44]`
 
-
+Provide the secret data of the TSIG key, generated using tsig-keygen.
 
 ### <a name="bindzone"></a>`bind::zone`
 

manifests/init.pp

@@ -48,6 +48,9 @@
 #   Configuration of the [logging
 #   statement](https://bind9.readthedocs.io/en/latest/reference.html#logging-statement-grammar).
 #
+# @param keys
+#   Hash for creating Bind::Key resources.
+#
 # @param options
 #   Configuration of the [options
 #   statement](https://bind9.readthedocs.io/en/latest/reference.html#options-statement-grammar).
@@ -148,9 +151,6 @@
 #   in the `$zones` parameter. Also, individual resource records can override this value with the
 #   `ttl` key in their hashes. Reference: [RFC 2308](https://tools.ietf.org/html/rfc2308#section-4)
 #
-# @param keys
-#   Hash for creating Bind::Key resources.
-#
 class bind (
   Boolean $authoritative = false,
   Stdlib::Absolutepath $config_dir = '/etc/bind',
@@ -164,6 +164,7 @@
   Optional[String[1]] $dev_packages_ensure = undef,
   Optional[String[1]] $doc_packages_ensure = undef,
   String[1] $utils_packages_ensure = 'installed',
+  Hash $keys = {},
   Optional[Bind::Logging] $logging = undef,
   Optional[Bind::Options] $options = undef,
   Boolean $package_backport = false,
@@ -191,7 +192,6 @@
   String[1] $zone_default_rname = 'hostmaster',
   Integer[0] $zone_default_serial = 1,
   String[1] $zone_default_ttl = '2d',
-  Hash $keys = {},
 ) {
   contain bind::install
   contain bind::config

manifests/key.pp

@@ -1,7 +1,8 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# @summary Create TSIG key for zone updates in the configuration file for BIND domain name server.
-#   Technical details: https://bind9.readthedocs.io/en/latest/advanced.html#tsig
+# @summary Create TSIG key for zone updates in the configuration file for BIND
+#
+# @see https://bind9.readthedocs.io/en/latest/advanced.html#tsig
 #
 # @example Add a TSIG key to the nameserver
 #   bind::key { 'tsig-client':
@@ -16,7 +17,6 @@
 #
 # @param secret
 #   Provide the secret data of the TSIG key, generated using tsig-keygen.
-
 define bind::key (
   Enum['hmac-sha256', 'hmac-sha384', 'hmac-sha512'] $algorithm,
   String[44] $secret,