Merge pull request #1020 from lionce/FM-7590

FM-7950 stringify stdlib

Author: carabasdaniel

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,10 +1,16 @@
-# 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.
+#   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
+  # @param key
+  # @param  message
+  # @return deprecated warnings
   dispatch :deprecation do
     param 'String', :key
     param 'String', :message

lib/facter/root_home.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 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/deprecation.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