(FM-7950) - Implement Puppet Strings

First Pass completed on types and strings
Functions from `a` to `m` done as well

Author: David Swan

REFERENCE.md

@@ -1,9 +1,13 @@
-# Function to print deprecation warnings, Logs a warning once for a given key. The uniqueness key - can appear once.
-# The msg is the message text including any positional information that is formatted by the user/caller of the method.
-# It is affected by the puppet setting 'strict', which can be set to :error (outputs as an error message),
-#   :off (no message / error is displayed) and :warning (default, outputs a warning)  *Type*: String, String.
+# @summary
+#   Function to print deprecation warnings, Logs a warning once for a given key.
+#
+# The uniqueness key - can appear once.
+# The msg is the message text including any positional information that is formatted by the
+# user/caller of the method.
+# It is affected by the puppet setting 'strict', which can be set to :error
+# (outputs as an error message), :off (no message / error is displayed) and :warning
+# (default, outputs a warning)  *Type*: String, String.
 #
-
 Puppet::Functions.create_function(:deprecation) do
   dispatch :deprecation do
     param 'String', :key

lib/puppet/functions/deprecation.rb

@@ -1,19 +1,25 @@
-# Digs into the facts hash using dot-notation
+# @summary
+#   Digs into the facts hash using dot-notation
 #
-# Example usage:
+# Supports the use of dot-notation for referring to structured facts. If a fact requested
+# does not exist, returns Undef.
 #
+# @example Example usage:
 #     fact('osfamily')
 #     fact('os.architecture')
 #
-# Array indexing:
-#
+# @example Array indexing:
 #     fact('mountpoints."/dev".options.1')
 #
-# Fact containing a "." in the name:
-#
+# @example Fact containing a "." in the name:
 #     fact('vmware."VRA.version"')
 #
 Puppet::Functions.create_function(:fact) do
+  # @param [String] fact_name
+  #   The name of the fact to check
+  #
+  # @return
+  #   All information retrieved on the given fact_name
   dispatch :fact do
     param 'String', :fact_name
   end

lib/puppet/functions/fact.rb

@@ -1,25 +1,35 @@
-# Boolean check to determine whether a variable is of a given data type. This is equivalent to the `=~` type checks.
+# @summary
+#   Boolean check to determine whether a variable is of a given data type.
+#   This is equivalent to the `=~` type checks.
 #
-# @example how to check a data type
+# @example Example Usage:
 #   # check a data type
-#       foo = 3
-#       $bar = [1,2,3]
-#       $baz = 'A string!'
+#     foo = 3
+#     $bar = [1,2,3]
+#     $baz = 'A string!'
 #
-#       if $foo.is_a(Integer) {
-#         notify  { 'foo!': }
-#       }
-#       if $bar.is_a(Array) {
-#         notify { 'bar!': }
-#       }
-#       if $baz.is_a(String) {
-#         notify { 'baz!': }
-#       }
+#     if $foo.is_a(Integer) {
+#       notify  { 'foo!': }
+#     }
+#     if $bar.is_a(Array) {
+#       notify { 'bar!': }
+#     }
+#     if $baz.is_a(String) {
+#       notify { 'baz!': }
+#     }
 #
 # See the documentation for "The Puppet Type System" for more information about types.
 # See the `assert_type()` function for flexible ways to assert the type of a value.
 #
 Puppet::Functions.create_function(:is_a) do
+  # @param value
+  #   The value to be checked
+  #
+  # @param type
+  #   The expected type
+  #
+  # @return [Boolean]
+  #   Return's `true` or `false`.
   dispatch :is_a do
     param 'Any', :value
     param 'Type', :type

lib/puppet/functions/is_a.rb

@@ -1,4 +1,14 @@
+# @summary
+#   Wrapper that calls the Puppet 3.x funtion of the same name.
 Puppet::Functions.create_function(:is_absolute_path) do
+  # @param scope
+  #   The main value that will be passed to the wrapped method
+  #
+  # @param args
+  #   Any additional values that are to be passed to the wrapped method
+  #
+  # @return [Boolea]
+  #   A boolean value returned from the called 3.x function.
   dispatch :deprecation_gen do
     param 'Any', :scope
     repeated_param 'Any', :args

lib/puppet/functions/is_absolute_path.rb

@@ -1,4 +1,14 @@
+# @summary
+#   Wrapper that calls the Puppet 3.x funtion of the same name.
 Puppet::Functions.create_function(:is_array) do
+  # @param scope
+  #   The main value that will be passed to the wrapped method
+  #
+  # @param args
+  #   Any additional values that are to be passed to the wrapped method
+  #
+  # @return [Boolea]
+  #   A boolean value returned from the called 3.x function.
   dispatch :deprecation_gen do
     param 'Any', :scope
     repeated_param 'Any', :args

lib/puppet/functions/is_array.rb

@@ -1,4 +1,14 @@
+# @summary
+#   Wrapper that calls the Puppet 3.x funtion of the same name.
 Puppet::Functions.create_function(:is_bool) do
+  # @param scope
+  #   The main value that will be passed to the wrapped method
+  #
+  # @param args
+  #   Any additional values that are to be passed to the wrapped method
+  #
+  # @return [Boolea]
+  #   A boolean value returned from the called 3.x function.
   dispatch :deprecation_gen do
     param 'Any', :scope
     repeated_param 'Any', :args

lib/puppet/functions/is_bool.rb

@@ -1,4 +1,14 @@
+# @summary
+#   Wrapper that calls the Puppet 3.x funtion of the same name.
 Puppet::Functions.create_function(:is_float) do
+  # @param scope
+  #   The main value that will be passed to the wrapped method
+  #
+  # @param args
+  #   Any additional values that are to be passed to the wrapped method
+  #
+  # @return [Boolea]
+  #   A boolean value returned from the called 3.x function.
   dispatch :deprecation_gen do
     param 'Any', :scope
     repeated_param 'Any', :args

lib/puppet/functions/is_float.rb

@@ -1,4 +1,14 @@
+# @summary
+#   Wrapper that calls the Puppet 3.x funtion of the same name.
 Puppet::Functions.create_function(:is_ip_address) do
+  # @param scope
+  #   The main value that will be passed to the wrapped method
+  #
+  # @param args
+  #   Any additional values that are to be passed to the wrapped method
+  #
+  # @return [Boolea]
+  #   A boolean value returned from the called 3.x function.
   dispatch :deprecation_gen do
     param 'Any', :scope
     repeated_param 'Any', :args

lib/puppet/functions/is_ip_address.rb

@@ -1,4 +1,14 @@
+# @summary
+#   Wrapper that calls the Puppet 3.x funtion of the same name.
 Puppet::Functions.create_function(:is_ipv4_address) do
+  # @param scope
+  #   The main value that will be passed to the wrapped method
+  #
+  # @param args
+  #   Any additional values that are to be passed to the wrapped method
+  #
+  # @return [Boolea]
+  #   A boolean value returned from the called 3.x function.
   dispatch :deprecation_gen do
     param 'Any', :scope
     repeated_param 'Any', :args