code reviewagelcg/chef-sugar2

Signed-off-by: Lamont Granquist <lamont@scriptkiddie.org>

5 files changed, 62 insertions, 8 deletions

diff --git a/chef-utils/lib/chef-utils/dsl/platform.rb b/chef-utils/lib/chef-utils/dsl/platform.rb
index c8c46d97b0..29f6b1563c 100644
--- a/chef-utils/lib/chef-utils/dsl/platform.rb
+++ b/chef-utils/lib/chef-utils/dsl/platform.rb
@@ -274,10 +274,10 @@ module ChefUtils
       #
       # @return [Boolean]
       #
-      def mac_os_x_platform?(node = __getnode)
+      def macos_platform?(node = __getnode)
         node["platform"] == "mac_os_x"
       end
-      alias_method :macos_platform?, :mac_os_x_platform?
+      alias_method :mac_os_x_platform?, :macos_platform?
 
       # Determine if the current node is gentoo
       #
diff --git a/chef-utils/lib/chef-utils/dsl/platform_family.rb b/chef-utils/lib/chef-utils/dsl/platform_family.rb
index f77514c218..477d51c9a4 100644
--- a/chef-utils/lib/chef-utils/dsl/platform_family.rb
+++ b/chef-utils/lib/chef-utils/dsl/platform_family.rb
@@ -70,12 +70,12 @@ module ChefUtils
       #
       # @return [Boolean]
       #
-      def mac_os_x?(node = __getnode)
+      def macos?(node = __getnode)
         node["platform_family"] == "mac_os_x"
       end
-      alias_method :osx?, :mac_os_x?
-      alias_method :mac?, :mac_os_x?
-      alias_method :macos?, :mac_os_x?
+      alias_method :osx?, :macos?
+      alias_method :mac?, :macos?
+      alias_method :mac_os_x?, :macos?
 
       # Determine if the current node is a member of the redhat family.
       #
diff --git a/chef-utils/lib/chef-utils/dsl/which.rb b/chef-utils/lib/chef-utils/dsl/which.rb
index 8e89f47827..1d4ddcc4d0 100644
--- a/chef-utils/lib/chef-utils/dsl/which.rb
+++ b/chef-utils/lib/chef-utils/dsl/which.rb
@@ -22,10 +22,59 @@ module ChefUtils
     module Which
       include Internal
 
+      # Lookup an executable through the systems search PATH.  Allows specifying an array
+      # of executables to look for.  The first executable that is found, along any path entry,
+      # will be the preferred one and returned first.  The extra_path will override any default
+      # extra_paths which are added (allwing the user to pass an empty array to remove them).
+      #
+      # When passed a block the block will be called with the full pathname of any executables
+      # which are found, and the block should return truthy or falsey values to further filter
+      # the executable based on arbitrary criteria.
+      #
+      # This is syntactic sugar for `where(...).first`
+      #
+      # This helper can be used in target mode in chef or with train using the appropriate
+      # wiring extenerally.
+      #
+      # @example Find the most appropriate python executable, searching through the system PATH
+      #          plus additionally the "/usr/libexec" directory, which has the dnf libraries
+      #          installed and available.
+      #
+      #   cmd = which("platform-python", "python", "python3", "python2", "python2.7", extra_path: "/usr/libexec") do |f|
+      #     shell_out("#{f} -c 'import dnf'").exitstatus == 0
+      #   end
+      #
+      # @param [Array<String>] list of commands to search for
+      # @param [String,Array<String>] array of extra paths to search through
+      # @return [String] the first match
+      #
       def which(*cmds, extra_path: nil, &block)
         where(*cmds, extra_path: extra_path, &block).first || false
       end
 
+      # Lookup all the instances of an an executable that can be found through the systems search PATH.
+      # Allows specifying an array of executables to look for.  All the instances of the first executable
+      # that is found will be returned first.  The extra_path will override any default extra_paths
+      # which are added (allwing the user to pass an empty array to remove them).
+      #
+      # When passed a block the block will be called with the full pathname of any executables
+      # which are found, and the block should return truthy or falsey values to further filter
+      # the executable based on arbitrary criteria.
+      #
+      # This helper can be used in target mode in chef or with train using the appropriate
+      # wiring extenerally.
+      #
+      # @example Find all the python executable, searching through the system PATH plus additionally
+      #          the "/usr/libexec" directory, which have the dnf libraries installed and available.
+      #
+      #   cmds = where("platform-python", "python", "python3", "python2", "python2.7", extra_path: "/usr/libexec") do |f|
+      #     shell_out("#{f} -c 'import dnf'").exitstatus == 0
+      #   end
+      #
+      # @param [Array<String>] list of commands to search for
+      # @param [String,Array<String>] array of extra paths to search through
+      # @return [String] the first match
+      #
       def where(*cmds, extra_path: nil, &block)
         extra_path ||= __extra_path
         paths = __env_path.split(File::PATH_SEPARATOR) + Array(extra_path)
@@ -40,11 +89,16 @@ module ChefUtils
 
       private
 
+      # This is for injecting common extra_paths into the search PATH.  The chef-client codebase overrides this into its
+      # own custom mixin to ensure that /usr/sbin, /sbin, etc are in the search PATH for chef-client.
+      #
       # @api private
       def __extra_path
         nil
       end
 
+      # Windows compatible and train/target-mode-enhanced helper to determine if an executable is valid.
+      #
       # @api private
       def __valid_executable?(filename, &block)
         is_executable =
diff --git a/lib/chef/mixin/path_sanity.rb b/lib/chef/mixin/path_sanity.rb
index beb7c9b481..de59c063e9 100644
--- a/lib/chef/mixin/path_sanity.rb
+++ b/lib/chef/mixin/path_sanity.rb
@@ -18,8 +18,8 @@
 
 class Chef
   module Mixin
+    # @ deprecated
     module PathSanity
-      # FIXME: deprecatad
       def enforce_path_sanity(env = ENV)
         if Chef::Config[:enforce_path_sanity]
           env["PATH"] = ChefUtils::DSL::PathSanity.sanitized_path(env)
diff --git a/lib/chef/platform/service_helpers.rb b/lib/chef/platform/service_helpers.rb
index 58fdc45041..a97a6f2ef4 100644
--- a/lib/chef/platform/service_helpers.rb
+++ b/lib/chef/platform/service_helpers.rb
@@ -21,7 +21,7 @@ require "chef-utils" if defined?(ChefUtils::CANARY)
 
 class Chef
   class Platform
-    # FIXME: deprecated, use ChefUtils::Service instead
+    # @deprecated, use ChefUtils::DSL::Service instead (via the ChefUtils Universal DSL)
     class ServiceHelpers
       class << self
         def service_resource_providers