Convert documentation to puppet-strings

manifests/config.pp

@@ -1,4 +1,5 @@
 # Configure dns
+# @api private
 class dns::config {
   group { $dns::params::group: }
 

manifests/init.pp

@@ -1,98 +1,82 @@
-# == Class: dns
-#
-# Install, configure and start dns service
-#
-# === Parameters:
-# $namedconf_path::             Path of the named config
-#
-# $dnsdir::                     Directory holding the named configs
-#
-# $dns_server_package::         Name of the package to install
-#
-# $rndckeypath::                Path of the RNDC key
-#
-# $optionspath::                Path of the named options
-#
-# $publicviewpath::             Path of the config file holding all the zones
-#
-# $vardir::                     Directory holding the variable or working files
-#
-# $namedservicename::           Name of the service
-#
-# $zonefilepath::               Directory containing zone files
-#
-# $localzonepath::              File holding local zones like RFC1912 or RFC1918 files.
-#                               The special value 'unmanaged' can be used if one plans
-#                               to create custom RFC1912/RFC1918 zones via ::dns,
-#                               where the inclusion of package-shipped zone files is
-#                               not desired.
-#
-# $defaultzonepath::            File holding some RFC1912 zone includes on systems
-#                               like Debian.
-#                               The special value 'unmanaged' can be used if one plans
-#                               to create custom zones via ::dns,
-#                               where the inclusion of package-shipped zone files is
-#                               not desired.
-#
-# $forward::                    The forward option
-#
-# $forwarders::                 The forwarders option
-#
-# $listen_on_v6::               The listen-on-v6 option
-#
-# $recursion::                  The recursion option
-#
-# $allow_recursion::            The allow-recursion option
-#
-# $allow_query::                The allow-query option
-#
-# $empty_zones_enable::         The empty-zones-enable option
-#
-# $dns_notify::                 The notify option in named.conf
-#
-# $dnssec_enable::              The dnssec-enable option
-#
-# $dnssec_validation::          The dnssec-validation option
-#
-# $namedconf_template::         The template to be used for named.conf
-#
-# $acls::                       Specify a hash of ACLs. Each key is the
-#                               name of a network, and its value is
-#                               an array of subnet strings.
-#
-# $optionsconf_template::       The template to be used for options.conf
-#
-# $controls::                   Specify a hash of controls. Each key is the
-#                               name of a network, and its value is a hash
-#                               containing 'port' => integer, 'keys' => array
-#                               and 'allowed_addresses' => array
-#
-# $service_ensure::             The ensure attribute on the service
-#
-# $service_enable::             Whether to enable the service (start at boot)
-#
-# $additional_options::         Additional options
-#
-# $additional_directives::      Additional directives. These are free form
-#                               strings that allow for full customization. Use
-#                               with caution.
-#
-# $enable_views::               Flag to indicate bind views support. Will remove
-#                               global zone configuration like localzonepath
-#                               inclusion.
-#
-# $zones::                      A hash of zones to be created. See dns::zone
-#                               for options.
-#
-# $keys::                       A hash of keys to be created. See dns::key for
-#                               options.
-#
-# === Usage:
-#
-# * Simple usage:
-#
-#     include dns
-#
+# Manage an ISC BIND nameserver
+#
+# @param namedconf_path
+#   Path of the named config
+# @param dnsdir
+#   Directory holding the named configs
+# @param dns_server_package
+#   Name of the package to install
+# @param rndckeypath
+#   Path of the RNDC key
+# @param optionspath
+#   Path of the named options
+# @param publicviewpath
+#   Path of the config file holding all the zones
+# @param vardir
+#   Directory holding the variable or working files
+# @param namedservicename
+#   Name of the service
+# @param zonefilepath
+#   Directory containing zone files
+# @param localzonepath
+#   File holding local zones like RFC1912 or RFC1918 files.  The special value
+#   'unmanaged' can be used if one plans to create custom RFC1912/RFC1918 zones
+#   via dns, where the inclusion of package-shipped zone files is not desired.
+# @param defaultzonepath
+#   File holding some RFC1912 zone includes on systems like Debian.
+#   The special value 'unmanaged' can be used if one plans to create custom
+#   zones via dns, where the inclusion of package-shipped zone files is not
+#   desired.
+# @param forward
+#   The forward option
+# @param forwarders
+#   The forwarders option
+# @param listen_on_v6
+#   The listen-on-v6 option
+# @param recursion
+#   The recursion option
+# @param allow_recursion
+#   The allow-recursion option
+# @param allow_query
+#   The allow-query option
+# @param empty_zones_enable
+#   The empty-zones-enable option
+# @param dns_notify
+#   The notify option in named.conf
+# @param dnssec_enable
+#   The dnssec-enable option
+# @param dnssec_validation
+#   The dnssec-validation option
+# @param namedconf_template
+#   The template to be used for named.conf
+# @param acls
+#   Specify a hash of ACLs. Each key is the name of a network, and its value is
+#   an array of subnet strings.
+# @param optionsconf_template
+#   The template to be used for options.conf
+# @param controls
+#   Specify a hash of controls. Each key is the name of a network, and its
+#   value is a hash containing 'port' => integer, 'keys' => array and
+#   'allowed_addresses' => array
+# @param service_ensure
+#   The ensure attribute on the service
+# @param service_enable
+#   Whether to enable the service (start at boot)
+# @param additional_options
+#   Additional options
+# @param additional_directives
+#   Additional directives. These are free form strings that allow for full
+#   customization. Use with caution.
+# @param enable_views
+#   Flag to indicate bind views support. Will remove global zone configuration
+#   like localzonepath inclusion.
+# @param zones
+#   A hash of zones to be created. See dns::zone for options.
+# @param keys
+#   A hash of keys to be created. See dns::key for options.
+#
+# @see dns::zone
+# @see dns::key
 class dns (
   Stdlib::Absolutepath $namedconf_path                              = $dns::params::namedconf_path,
   Stdlib::Absolutepath $dnsdir                                      = $dns::params::dnsdir,

manifests/install.pp

@@ -1,4 +1,5 @@
 # Install dns service
+# @api private
 class dns::install {
   if ! empty($dns::dns_server_package) {
     ensure_packages([$dns::dns_server_package])

manifests/key.pp

@@ -1,8 +1,21 @@
 # Generate a new key for the dns
 #
-# === Parameters:
+# @param algorithm
+#   The algorithm used to generate the secret key
 #
-# $secret::                     This is the secret to be place inside the keyfile, if left empty the key will be generated
+# @param filename
+#   The filename to store the key. This is placed in the key directory.
+#
+# @param secret
+#   This is the secret to be place inside the keyfile, if left empty the key
+#   will be generated
+#
+# @param keydir
+#   The directory to store the key in. Inherited from the main dns class by default.
+#
+# @param keysize
+#   The size of the key to generate. Only used when generating the key. It's
+#   ignored if when a key is specified.
 #
 define dns::key(
   String               $algorithm    = 'hmac-md5',

manifests/params.pp

@@ -1,4 +1,5 @@
 # Default parameters
+# @api private
 class dns::params {
   case $facts['osfamily'] {
     'Debian': {

manifests/service.pp

@@ -1,4 +1,5 @@
 # Enable and start dns service
+# @api private
 class dns::service {
   service { $dns::namedservicename:
     ensure     => $dns::service_ensure,

manifests/zone.pp

@@ -1,15 +1,17 @@
 # Define new zone for the dns
 #
-# === Parameters:
+# @param manage_file
+#   Whether the manage the file resource. When true $manage_file_name is implied.
 #
-# $manage_file::                Whether the manage the file resource. When true $manage_file_name is implied.
+# @param manage_file_name
+#   Whether to set the file parameter in the zone file.
 #
-# $manage_file_name::           Whether to set the file parameter in the zone file.
-#
-# $update_policy_rules::        This can be used to specifiy additional update policy rules in the following format
-#                               { '<KEY_NAME' => {'matchtype' => '<VALUE>', 'tname' => '<VALUE>', 'rr' => 'VALUE' } }
-#                               Example {'foreman_key' => {'matchtype' => 'zonesub', 'rr' => 'ANY'}}
-#                               tname and rr are optional
+# @param update_policy_rules
+#   This can be used to specifiy additional update policy rules in the
+#   following format
+#   { '<KEY_NAME' => {'matchtype' => '<VALUE>', 'tname' => '<VALUE>', 'rr' => 'VALUE' } }
+#   Example {'foreman_key' => {'matchtype' => 'zonesub', 'rr' => 'ANY'}}
+#   tname and rr are optional
 #
 define dns::zone (
   Array[String] $target_views                           = [],