FM-7590 - strings

Author: lionce

README.md

@@ -1,5 +1,6 @@
-# A Facter plugin that loads facts from /etc/facter/facts.d
-# and /etc/puppetlabs/facter/facts.d.
+# @summary
+#   A Facter plugin that loads facts from /etc/facter/facts.d
+#   and /etc/puppetlabs/facter/facts.d.
 #
 # Facts can be in the form of JSON, YAML or Text files
 # and any executable that returns key=value pairs.
@@ -13,20 +14,23 @@
 # fact scripts more often than is needed
 class Facter::Util::DotD
   require 'yaml'
-
+  # These will be nil if Puppet is not available.
   def initialize(dir = '/etc/facts.d', cache_file = File.join(Puppet[:libdir], 'facts_dot_d.cache'))
     @dir = dir
     @cache_file = cache_file
     @cache = nil
     @types = { '.txt' => :txt, '.json' => :json, '.yaml' => :yaml }
   end
 
+  # entries
   def entries
     Dir.entries(@dir).reject { |f| f =~ %r{^\.|\.ttl$} }.sort.map { |f| File.join(@dir, f) }
   rescue
     []
   end
 
+  # fact_type
+  # @param file
   def fact_type(file)
     extension = File.extname(file)
 
@@ -37,6 +41,8 @@ def fact_type(file)
     type
   end
 
+  # txt_parser
+  # @param file
   def txt_parser(file)
     File.readlines(file).each do |line|
       next unless line =~ %r{^([^=]+)=(.+)$}
@@ -51,6 +57,8 @@ def txt_parser(file)
     Facter.warn("Failed to handle #{file} as text facts: #{e.class}: #{e}")
   end
 
+  # json_parser
+  # @param file
   def json_parser(file)
     begin
       require 'json'
@@ -68,6 +76,8 @@ def json_parser(file)
     Facter.warn("Failed to handle #{file} as json facts: #{e.class}: #{e}")
   end
 
+  # yaml_parser
+  # @param file
   def yaml_parser(file)
     require 'yaml'
 
@@ -80,6 +90,8 @@ def yaml_parser(file)
     Facter.warn("Failed to handle #{file} as yaml facts: #{e.class}: #{e}")
   end
 
+  # script_parser
+  # @param file
   def script_parser(file)
     result = cache_lookup(file)
     ttl = cache_time(file)
@@ -110,19 +122,24 @@ def script_parser(file)
     Facter.debug(e.backtrace.join("\n\t"))
   end
 
+  # cache_save
   def cache_save!
     cache = load_cache
     File.open(@cache_file, 'w', 0o600) { |f| f.write(YAML.dump(cache)) }
   rescue # rubocop:disable Lint/HandleExceptions
   end
 
+  # cache_store
+  # @param file
   def cache_store(file, data)
     load_cache
 
     @cache[file] = { :data => data, :stored => Time.now.to_i }
   rescue # rubocop:disable Lint/HandleExceptions
   end
 
+  # cache_lookup
+  # @param file
   def cache_lookup(file)
     cache = load_cache
 
@@ -140,6 +157,8 @@ def cache_lookup(file)
     return nil
   end
 
+  # cache_time
+  # @param file
   def cache_time(file)
     meta = file + '.ttl'
 
@@ -148,6 +167,7 @@ def cache_time(file)
     return 0
   end
 
+  # load_cache
   def load_cache
     @cache ||= if File.exist?(@cache_file)
                  YAML.load_file(@cache_file)
@@ -161,6 +181,7 @@ def load_cache
     return @cache
   end
 
+  # create
   def create
     entries.each do |fact|
       type = fact_type(fact)

REFERENCE.md

@@ -10,7 +10,9 @@
 require 'puppet/type'
 require 'puppet/type/package'
 
+# These will be nil if Puppet is not available.
 Facter.add(:package_provider) do
+  # Instantiates a dummy package resource and return the provider
   setcode do
     if defined? Gem && Gem::Version.new(Facter.value(:puppetversion).split(' ')[0]) >= Gem::Version.new('3.6')
       Puppet::Type.type(:package).newpackage(:name => 'dummy', :allow_virtual => 'true')[:provider].to_s

lib/facter/facter_dot_d.rb

@@ -8,6 +8,7 @@
 #
 # Caveats:
 #
+# Fact: pe_version
 Facter.add('pe_version') do
   setcode do
     puppet_ver = Facter.value('puppetversion')
@@ -20,6 +21,7 @@
   end
 end
 
+# Fact: is_pe
 Facter.add('is_pe') do
   setcode do
     if Facter.value(:pe_version).to_s.empty?
@@ -30,6 +32,7 @@
   end
 end
 
+# Fact: pe_major_version
 Facter.add('pe_major_version') do
   confine :is_pe => true
   setcode do
@@ -40,6 +43,7 @@
   end
 end
 
+# Fact: pe_minor_version
 Facter.add('pe_minor_version') do
   confine :is_pe => true
   setcode do
@@ -50,6 +54,7 @@
   end
 end
 
+# Fact: pe_patch_version
 Facter.add('pe_patch_version') do
   confine :is_pe => true
   setcode do

lib/facter/package_provider.rb

@@ -16,7 +16,7 @@
   load rb_file if File.exist?(rb_file) || raise(e)
 end
 
-# These will be nil if Puppet is not available.
+# Facter fact returns the value of the Puppet vardir
 Facter.add(:puppet_vardir) do
   setcode do
     Facter::Util::PuppetSettings.with_puppet do
@@ -25,6 +25,7 @@
   end
 end
 
+# Facter fact returns the value of the Puppet environment path
 Facter.add(:puppet_environmentpath) do
   setcode do
     Facter::Util::PuppetSettings.with_puppet do
@@ -33,6 +34,7 @@
   end
 end
 
+# Facter fact returns the value of the Puppet server
 Facter.add(:puppet_server) do
   setcode do
     Facter::Util::PuppetSettings.with_puppet do

lib/facter/pe_version.rb

@@ -1,8 +1,11 @@
-# A facter fact to determine the root home directory.
-# This varies on PE supported platforms and may be
-# reconfigured by the end user.
+# root_home.rb
 module Facter::Util::RootHome
+  # @summary
+  #   A facter fact to determine the root home directory.
+  #   This varies on PE supported platforms and may be
+  #   reconfigured by the end user.
   class << self
+  # determines the root home directory
   def returnt_root_home
     root_ent = Facter::Util::Resolution.exec('getent passwd root')
     # The home directory is the sixth element in the passwd entry

lib/facter/puppet_settings.rb

@@ -1,4 +1,3 @@
-# @summary
 #   Function to print deprecation warnings, Logs a warning once for a given key.
 #
 # The uniqueness key - can appear once.
@@ -9,6 +8,9 @@
 # (default, outputs a warning)  *Type*: String, String.
 #
 Puppet::Functions.create_function(:deprecation) do
+  # @param key
+  # @param  message
+  # @return deprecated warnings
   dispatch :deprecation do
     param 'String', :key
     param 'String', :message

lib/facter/root_home.rb

@@ -15,7 +15,7 @@
 #     fact('vmware."VRA.version"')
 #
 Puppet::Functions.create_function(:fact) do
-  # @param [String] fact_name
+  # @param fact_name
   #   The name of the fact to check
   #
   # @return

lib/puppet/functions/deprecation.rb

@@ -7,7 +7,7 @@
   # @param args
   #   Any additional values that are to be passed to the wrapped method
   #
-  # @return [Boolea]
+  # @return [Boolean]
   #   A boolean value returned from the called 3.x function.
   dispatch :deprecation_gen do
     param 'Any', :scope

lib/puppet/functions/fact.rb

@@ -1,11 +1,16 @@
-# Checks if the OS version is at least a certain version. Note that only the
-# major version is taken into account.
-#
-# Example usage:
+# @summary
+#   Checks if the OS version is at least a certain version.
+# > *Note:*
+# Only the major version is taken into account.
 #
+# @example Example usage:#
 #     if os_version_gte('Debian', '9') { }
 #     if os_version_gte('Ubuntu', '18.04') { }
 Puppet::Functions.create_function(:os_version_gte) do
+  # @param os operating system
+  # @param version
+  #
+  # @return [Boolean] `true` or `false
   dispatch :os_version_gte do
     param 'String[1]', :os
     param 'String[1]', :version

lib/puppet/functions/is_string.rb

@@ -1,4 +1,5 @@
-# Generates a consistent random string of specific length based on provided seed.
+# @summary
+#   Generates a consistent random string of specific length based on provided seed.
 #
 # @example Generate a consistently random string of length 8 with a seed:
 #   seeded_rand_string(8, "${module_name}::redis_password")

lib/puppet/functions/os_version_gte.rb

@@ -1,4 +1,5 @@
-# Uses sprintf with named references.
+# @summary
+#  Uses sprintf with named references.
 #
 # The first parameter is format string describing how the rest of the parameters in the hash
 # should be formatted. See the documentation for the `Kernel::sprintf` function in Ruby for

lib/puppet/functions/seeded_rand_string.rb

@@ -4,8 +4,8 @@
 # @example ip_in_range(<IPv4 Address>, <IPv4 CIDR>)
 #   stdlib::ip_in_range('10.10.10.53', '10.10.10.0/24') => true
 Puppet::Functions.create_function(:'stdlib::ip_in_range') do
-  # @param [String] ipaddress The IP address to check
-  # @param [Variant[String, Array]] range One CIDR or an array of CIDRs
+  # @param ipaddress The IP address to check
+  # @param range One CIDR or an array of CIDRs
   #   defining the range(s) to check against
   #
   # @return [Boolean] True or False
@@ -16,7 +16,6 @@
   end
 
   require 'ipaddr'
-
   def ip_in_range(ipaddress, range)
     ip = IPAddr.new(ipaddress)
 

lib/puppet/functions/sprintf_hash.rb

@@ -1,4 +1,6 @@
-# Take a data structure and output it as JSON
+require 'json'
+# @summary
+#   Convert a data structure and output to JSON
 #
 # @example how to output JSON
 #   # output json to a file
@@ -7,10 +9,10 @@
 #       content => to_json($myhash),
 #     }
 #
-#
-require 'json'
-
 Puppet::Functions.create_function(:to_json) do
+  # @param data
+  #   data structure which needs to be converted into JSON
+  # @return converted data to json
   dispatch :to_json do
     param 'Any', :data
   end

lib/puppet/functions/stdlib/ip_in_range.rb

@@ -1,25 +1,29 @@
-# Take a data structure and output it as pretty JSON
+require 'json'
+# @summary
+#   Convert data structure and output to pretty JSON
 #
-# @example how to output pretty JSON
-#   # output pretty json to a file
+# @example **Usage**
+#   * how to output pretty JSON to file
 #     file { '/tmp/my.json':
 #       ensure  => file,
 #       content => to_json_pretty($myhash),
 #     }
 #
-# @example how to output pretty JSON skipping over keys with undef values
-#   # output pretty JSON to a file skipping over undef values
+#   * how to output pretty JSON skipping over keys with undef values
 #     file { '/tmp/my.json':
 #       ensure  => file,
 #       content => to_json_pretty({
 #         param_one => 'value',
 #         param_two => undef,
 #       }),
 #     }
-#
-require 'json'
-
 Puppet::Functions.create_function(:to_json_pretty) do
+  # @param data
+  #   data structure which needs to be converted to pretty json
+  # @param skip_undef
+  #   value `true` or `false`
+  # @return
+  #   converted data to pretty json
   dispatch :to_json_pretty do
     param 'Variant[Hash, Array]', :data
     optional_param 'Boolean', :skip_undef

lib/puppet/functions/to_json.rb

@@ -1,16 +1,17 @@
-# Take a data structure and output it as YAML
+require 'yaml'
+# @summary
+#   Convert a data structure and output it as YAML
 #
 # @example how to output YAML
 #   # output yaml to a file
 #     file { '/tmp/my.yaml':
 #       ensure  => file,
 #       content => to_yaml($myhash),
 #     }
-#
-#
-require 'yaml'
-
 Puppet::Functions.create_function(:to_yaml) do
+  # @param data
+  #
+  # @return [String]
   dispatch :to_yaml do
     param 'Any', :data
   end

lib/puppet/functions/to_json_pretty.rb

@@ -1,4 +1,5 @@
-# Returns the type when passed a value.
+# @summary
+#   Returns the type of the passed value.
 #
 # @example how to compare values' types
 #   # compare the types of two values
@@ -13,6 +14,10 @@
 # The built-in type() function in puppet is generally preferred over this function
 # this function is provided for backwards compatibility.
 Puppet::Functions.create_function(:type_of) do
+  # @return [String]
+  #   the type of the passed value
+  #
+  # @param value
   def type_of(value)
     Puppet::Pops::Types::TypeCalculator.infer_set(value)
   end