(FM-7923) Implement Puppet Strings (puppetlabs#1916)

* (FM-7923) - Implement Puppet Strings.
Authors: 
 David Swan david.swan@puppet.com
 Eimhin Laverty eimhin.laverty@puppet.com
 Claire Cadman claire.cadman@puppet.com

Author: eimlav

README.md

@@ -1,8 +1,14 @@
-# Hashes a password in a format suitable for htpasswd files read by apache.
+# @summary
+#   Hashes a password in a format suitable for htpasswd files read by apache.
 #
 # Currently uses SHA-hashes, because although this format is considered insecure, its the
 # most secure format supported by the most platforms.
 Puppet::Functions.create_function(:'apache::apache_pw_hash') do
+  # @param password
+  #   The input that is to be hashed.
+  #
+  # @return
+  #   Return's the hash of the input that was given.
   dispatch :apache_pw_hash do
     required_param 'String[1]', :password
     return_type 'String'

REFERENCE.md

@@ -1,18 +1,21 @@
-# Transform a supposed boolean to On or Off. Pass all other values through.
-# Given a nil value (undef), bool2httpd will return 'Off'
+# @summary
+#   Transform a supposed boolean to On or Off. Passes all other values through.
 #
-# Example:
-#
-#    $trace_enable     = false
-#    $server_signature = 'mail'
-#
-#    bool2httpd($trace_enable)
-#    # => 'Off'
-#    bool2httpd($server_signature)
-#    # => 'mail'
-#    bool2httpd(undef)
-#    # => 'Off'
 Puppet::Functions.create_function(:'apache::bool2httpd') do
+  # @param arg
+  #   The value to be converted into a string.
+  #
+  # @return
+  #   Will return either `On` or `Off` if given a boolean value. Return's a string of any
+  #   other given value.
+  # @example
+  #   $trace_enable     = false
+  #   $server_signature = 'mail'
+  #
+  #   bool2httpd($trace_enable) # returns 'Off'
+  #   bool2httpd($server_signature) # returns 'mail'
+  #   bool2httpd(undef) # returns 'Off'
+  #
   def bool2httpd(arg)
     return 'Off' if arg.nil? || arg == false || arg =~ %r{false}i || arg == :undef
     return 'On' if arg == true || arg =~ %r{true}i

lib/puppet/functions/apache/apache_pw_hash.rb

@@ -1,15 +1,22 @@
-#    Perform simple validation of a string against the list of known log
-#    levels as per http://httpd.apache.org/docs/current/mod/core.html#loglevel
-#        validate_apache_loglevel('info')
+# @summary
+#   Perform simple validation of a string against the list of known log levels.
 #
-#    Modules maybe specified with their own levels like these:
-#        validate_apache_loglevel('warn ssl:info')
-#        validate_apache_loglevel('warn mod_ssl.c:info')
-#        validate_apache_loglevel('warn ssl_module:info')
+# As per http://httpd.apache.org/docs/current/mod/core.html#loglevel
+#     * validate_apache_loglevel('info')
 #
-#    Expected to be used from the main or vhost.
-#    Might be used from directory too later as apache supports that
+# Modules maybe specified with their own levels like these:
+#     * validate_apache_loglevel('warn ssl:info')
+#     * validate_apache_loglevel('warn mod_ssl.c:info')
+#     * validate_apache_loglevel('warn ssl_module:info')
+#
+# Expected to be used from the main or vhost.
+# Might be used from directory too later as apache supports that
 Puppet::Functions.create_function(:'apache::validate_apache_log_level') do
+  # @param log_level
+  #   The string that is to be validated.
+  #
+  # @return
+  #   Return's an error if the validation fails.
   dispatch :validate_apache_log_level do
     required_param 'String', :log_level
   end

lib/puppet/functions/apache/bool2httpd.rb

@@ -1,9 +1,17 @@
 require 'base64'
 
 Puppet::Parser::Functions.newfunction(:apache_pw_hash, type: :rvalue, doc: <<-DOC
-  Hashes a password in a format suitable for htpasswd files read by apache.
+  @summary
+    Hashes a password in a format suitable for htpasswd files read by apache.
+
   Currently uses SHA-hashes, because although this format is considered insecure, its the
   most secure format supported by the most platforms.
+
+  @param password
+    The input that is to be hashed.
+
+  @return
+    Return's the hash of the input that was given.
 DOC
                                      ) do |args|
   raise(Puppet::ParseError, "apache_pw_hash() wrong number of arguments. Given: #{args.size} for 1)") if args.size != 1

lib/puppet/functions/apache/validate_apache_log_level.rb

@@ -1,15 +1,21 @@
 Puppet::Parser::Functions.newfunction(:bool2httpd, type: :rvalue, doc: <<-DOC
-  Transform a supposed boolean to On or Off. Pass all other values through.
-  Given a nil value (undef), bool2httpd will return 'Off'
-  Example:
-      $trace_enable     = false
-      $server_signature = 'mail'
-      bool2httpd($trace_enable)
-      # => 'Off'
-      bool2httpd($server_signature)
-      # => 'mail'
-      bool2httpd(undef)
-      # => 'Off'
+  @summary
+    Transform a supposed boolean to On or Off. Pass all other values through.
+
+  @param arg
+    The value to be converted into a string.
+
+  @return
+    Will return either `On` or `Off` if given a boolean value. Return's a string of any
+    other given value.
+
+  @example
+    $trace_enable     = false
+    $server_signature = 'mail'
+
+    bool2httpd($trace_enable) # returns 'Off'
+    bool2httpd($server_signature) # returns 'mail'
+    bool2httpd(undef) # returns 'Off'
 DOC
                                      ) do |args|
   raise(Puppet::ParseError, "bool2httpd() wrong number of arguments. Given: #{args.size} for 1)") if args.size != 1

lib/puppet/parser/functions/apache_pw_hash.rb

@@ -1,15 +1,23 @@
 # validate_apache_log_level.rb
 module Puppet::Parser::Functions
   newfunction(:validate_apache_log_level, doc: <<-DOC
-    Perform simple validation of a string against the list of known log
-    levels as per http://httpd.apache.org/docs/current/mod/core.html#loglevel
-        validate_apache_loglevel('info')
+    @summary
+      Perform simple validation of a string against the list of known log levels.
+
+    As per http://httpd.apache.org/docs/current/mod/core.html#loglevel
+        * validate_apache_loglevel('info')
     Modules maybe specified with their own levels like these:
-        validate_apache_loglevel('warn ssl:info')
-        validate_apache_loglevel('warn mod_ssl.c:info')
-        validate_apache_loglevel('warn ssl_module:info')
+        * validate_apache_loglevel('warn ssl:info')
+        * validate_apache_loglevel('warn mod_ssl.c:info')
+        * validate_apache_loglevel('warn ssl_module:info')
     Expected to be used from the main or vhost.
     Might be used from directory too later as apaceh supports that
+
+    @param log_level
+      The string that is to be validated.
+
+    @return
+      Return's an error if the validation fails.
 DOC
              ) do |args|
     if args.size != 1

lib/puppet/parser/functions/bool2httpd.rb

@@ -1,5 +1,6 @@
 # a2mod.rb
 class Puppet::Provider::A2mod < Puppet::Provider
+  # Fetches the mod provider
   def self.prefetch(mods)
     instances.each do |prov|
       mod = mods[prov.name]
@@ -9,10 +10,12 @@ def self.prefetch(mods)
     end
   end
 
+  # Clear's the property_hash
   def flush
     @property_hash.clear
   end
 
+  # Returns a copy of the property_hash
   def properties
     if @property_hash.empty?
       @property_hash = query || { ensure: :absent }
@@ -21,6 +24,7 @@ def properties
     @property_hash.dup
   end
 
+  # Returns the properties of the given mod if it exists.
   def query
     self.class.instances.each do |mod|
       if mod.name == name || mod.name.downcase == name
@@ -30,6 +34,7 @@ def query
     nil
   end
 
+  # Return's if the ensure property is absent or not
   def exists?
     properties[:ensure] != :absent
   end

lib/puppet/parser/functions/validate_apache_log_level.rb

@@ -1,49 +1,46 @@
-# == Define Resource Type: apache::balancer
+# @summary
+#   This type will create an apache balancer cluster file inside the conf.d
+#   directory. 
 #
-# This type will create an apache balancer cluster file inside the conf.d
-# directory. Each balancer cluster needs one or more balancer members (that can
+# Each balancer cluster needs one or more balancer members (that can
 # be declared with the apache::balancermember defined resource type). Using
 # storeconfigs, you can export the apache::balancermember resources on all
 # balancer members, and then collect them on a single apache load balancer
 # server.
 #
-# === Requirement/Dependencies:
+# @note 
+#   Currently requires the puppetlabs/concat module on the Puppet Forge and uses
+#   storeconfigs on the Puppet Master to export/collect resources from all
+#   balancer members.
 #
-# Currently requires the puppetlabs/concat module on the Puppet Forge and uses
-# storeconfigs on the Puppet Master to export/collect resources from all
-# balancer members.
+# @param name
+#   The namevar of the defined resource type is the balancer clusters name.<br />
+#   This name is also used in the name of the conf.d file
 #
-# === Parameters
+# @param proxy_set
+#   Configures key-value pairs to be used as a ProxySet lines in the configuration.
 #
-# [*name*]
-# The namevar of the defined resource type is the balancer clusters name.
-# This name is also used in the name of the conf.d file
+# @param target
+#   The path to the file the balancer definition will be written in.
 #
-# [*proxy_set*]
-# Hash, default empty. If given, each key-value pair will be used as a ProxySet
-# line in the configuration.
+# @param collect_exported
+#   Determines whether to use exported resources.<br />
+#   If you statically declare all of your backend servers, set this parameter to false to rely 
+#   on existing, declared balancer member resources. Also, use apache::balancermember with array 
+#   arguments.<br />
+#   To dynamically declare backend servers via exported resources collected on a central node, 
+#   set this parameter to true to collect the balancer member resources exported by the balancer 
+#   member nodes.<br />
+#   If you don't use exported resources, a single Puppet run configures all balancer members. If 
+#   you use exported resources, Puppet has to run on the balanced nodes first, then run on the 
+#   balancer.
 #
-# [*target*]
-# String, default undef. If given, path to the file the balancer definition will
-# be written.
+# @param options
+#   Specifies an array of [options](https://httpd.apache.org/docs/current/mod/mod_proxy.html#balancermember) 
+#   after the balancer URL, and accepts any key-value pairs available to `ProxyPass`.
 #
-# [*collect_exported*]
-# Boolean, default 'true'. True means 'collect exported @@balancermember
-# resources' (for the case when every balancermember node exports itself),
-# false means 'rely on the existing declared balancermember resources' (for the
-# case when you know the full set of balancermembers in advance and use
-# apache::balancermember with array arguments, which allows you to deploy
-# everything in 1 run)
-#
-# [*options*]
-# Array, default empty. If given, additional directives may be added to the
-# <Proxy balancer://xyz OPTIONS> block.
-#
-# === Examples
-#
-# Exporting the resource for a balancer member:
-#
-# apache::balancer { 'puppet00': }
+# @example
+#   apache::balancer { 'puppet00': }
 #
 define apache::balancer (
   $proxy_set = {},

lib/puppet/provider/a2mod.rb

@@ -1,43 +1,42 @@
-# == Define Resource Type: apache::balancermember
-#
+# @summary
+#   Defines members of `mod_proxy_balancer`
+# 
+# Sets up a balancer member inside a listening service configuration block in 
+# the load balancer's `apache.cfg`.
+#   
 # This type will setup a balancer member inside a listening service
 # configuration block in /etc/apache/apache.cfg on the load balancer.
-# currently it only has the ability to specify the instance name, url and an
+# Currently it only has the ability to specify the instance name, url and an
 # array of options. More features can be added as needed. The best way to
 # implement this is to export this resource for all apache balancer member
 # servers, and then collect them on the main apache load balancer.
 #
-# === Requirement/Dependencies:
-#
-# Currently requires the puppetlabs/concat module on the Puppet Forge and
-# uses storeconfigs on the Puppet Master to export/collect resources
-# from all balancer members.
-#
-# === Parameters
-#
-# [*name*]
-# The title of the resource is arbitrary and only utilized in the concat
-# fragment name.
-#
-# [*balancer_cluster*]
-# The apache service's instance name (or, the title of the apache::balancer
-# resource). This must match up with a declared apache::balancer resource.
+# @note
+#   Currently requires the puppetlabs/concat module on the Puppet Forge and
+#   uses storeconfigs on the Puppet Master to export/collect resources
+#   from all balancer members.
 #
-# [*url*]
-# The url used to contact the balancer member server.
+# @param name
+#   The title of the resource is arbitrary and only utilized in the concat
+#   fragment name.
 #
-# [*options*]
-# An array of options to be specified after the url.
+# @param balancer_cluster
+#   The apache service's instance name (or, the title of the apache::balancer
+#   resource). This must match up with a declared apache::balancer resource.
 #
-# === Examples
+# @param url
+#   The url used to contact the balancer member server.
 #
-# Exporting the resource for a balancer member:
+# @param  options
+#   Specifies an array of [options](https://httpd.apache.org/docs/current/mod/mod_proxy.html#balancermember) 
+#   after the URL, and accepts any key-value pairs available to `ProxyPass`.
 #
-# @@apache::balancermember { 'apache':
-#   balancer_cluster => 'puppet00',
-#   url              => "ajp://${::fqdn}:8009"
-#   options          => ['ping=5', 'disablereuse=on', 'retry=5', 'ttl=120'],
-# }
+# @example
+#   @@apache::balancermember { 'apache':
+#     balancer_cluster => 'puppet00',
+#     url              => "ajp://${::fqdn}:8009"
+#     options          => ['ping=5', 'disablereuse=on', 'retry=5', 'ttl=120'],
+#   }
 #
 define apache::balancermember(
   $balancer_cluster,

manifests/balancer.pp

@@ -1,3 +1,7 @@
+# @summary
+#   Manages the `no-accf.conf` file.
+#
+# @api private
 class apache::confd::no_accf {
   # Template uses no variables
   file { 'no-accf.conf':