Merge pull request #9327 from chef/chef_utils_yard

Swap the methods and the aliases in the chef-utils platforms

8 files changed, 122 insertions, 69 deletions

diff --git a/chef-utils/README.md b/chef-utils/README.md
index 668739c9c1..e44d4d6937 100644
--- a/chef-utils/README.md
+++ b/chef-utils/README.md
@@ -149,7 +149,7 @@ Architecture Helpers allow you to determine the processor architecture of your n
 * `openvz_host?` - if the node is an openvz host
 * `guest?` - if the node is detected as any kind of guest
 * `hypervisor?` - if the node is detected as being any kind of hypervisor
-* `physical?` - the node is not running as a guest (may be a hypervisor or may be plain metal)
+* `physical?` - the node is not running as a guest (may be a hypervisor or may be bare-metal)
 * `vagrant?` - attempts to identify the node as a vagrant guest (this check may be error prone)
 
 ### Train Helpers
diff --git a/chef-utils/lib/chef-utils/dsl/cloud.rb b/chef-utils/lib/chef-utils/dsl/cloud.rb
index 32911609cc..734c7412aa 100644
--- a/chef-utils/lib/chef-utils/dsl/cloud.rb
+++ b/chef-utils/lib/chef-utils/dsl/cloud.rb
@@ -76,6 +76,7 @@ module ChefUtils
       def eucalyptus?(node = __getnode)
         node.key?("eucalyptus")
       end
+      # chef-sugar backcompat method
       alias_method :euca?, :eucalyptus?
 
       # Return true if the current current node is in Linode.
@@ -121,6 +122,7 @@ module ChefUtils
       def digital_ocean?(node = __getnode)
         node.key?("digital_ocean")
       end
+      # chef-sugar backcompat method
       alias_method :digitalocean?, :digital_ocean?
 
       # Return true if the current current node is in SoftLayer.
diff --git a/chef-utils/lib/chef-utils/dsl/introspection.rb b/chef-utils/lib/chef-utils/dsl/introspection.rb
index 07c77aa3a8..ba65cf2881 100644
--- a/chef-utils/lib/chef-utils/dsl/introspection.rb
+++ b/chef-utils/lib/chef-utils/dsl/introspection.rb
@@ -113,6 +113,7 @@ module ChefUtils
       def includes_recipe?(recipe_name, node = __getnode)
         node.recipe?(recipe_name)
       end
+      # chef-sugar backcompat method
       alias_method :include_recipe?, :includes_recipe?
 
       extend self
diff --git a/chef-utils/lib/chef-utils/dsl/platform.rb b/chef-utils/lib/chef-utils/dsl/platform.rb
index d719f5de1c..8af405d51c 100644
--- a/chef-utils/lib/chef-utils/dsl/platform.rb
+++ b/chef-utils/lib/chef-utils/dsl/platform.rb
@@ -34,39 +34,43 @@ module ChefUtils
       #
       # @return [Boolean]
       #
-      def linuxmint?(node = __getnode)
+      def linuxmint_platform?(node = __getnode)
         node["platform"] == "linuxmint"
       end
-      # chef-sugar backcompat methods
-      alias_method :mint?, :linuxmint?
-      alias_method :linux_mint?, :linuxmint?
-      alias_method :linuxmint_platform?, :linuxmint?
+      # chef-sugar backcompat method
+      alias_method :mint?, :linuxmint_platform?
+      # chef-sugar backcompat method
+      alias_method :linux_mint?, :linuxmint_platform?
+      # chef-sugar backcompat method
+      alias_method :linuxmint?, :linuxmint_platform?
 
-      # Determine if the current node is ubuntu.
+      # Determine if the current node is Ubuntu.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
       #
       # @return [Boolean]
       #
-      def ubuntu?(node = __getnode)
+      def ubuntu_platform?(node = __getnode)
         node["platform"] == "ubuntu"
       end
-      alias_method :ubuntu_platform?, :ubuntu?
+      # chef-sugar backcompat method
+      alias_method :ubuntu?, :ubuntu_platform?
 
-      # Determine if the current node is raspbian.
+      # Determine if the current node is Raspbian.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
       #
       # @return [Boolean]
       #
-      def raspbian?(node = __getnode)
+      def raspbian_platform?(node = __getnode)
         node["platform"] == "raspbian"
       end
-      alias_method :raspbian_platform?, :raspbian?
+      # chef-sugar backcompat method
+      alias_method :raspbian?, :raspbian_platform?
 
-      # Determine if the current node is debian.
+      # Determine if the current node is Debian.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -77,7 +81,7 @@ module ChefUtils
         node["platform"] == "debian"
       end
 
-      # Determine if the current node is amazon linux.
+      # Determine if the current node is Amazon Linux.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -88,74 +92,80 @@ module ChefUtils
         node["platform"] == "amazon"
       end
 
-      # Determine if the current node is redhat enterprise.
+      # Determine if the current node is Red Hat Enterprise Linux.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
       #
       # @return [Boolean]
       #
-      def redhat?(node = __getnode)
+      def redhat_platform?(node = __getnode)
         node["platform"] == "redhat"
       end
-      # chef-sugar backcompat methods
-      alias_method :redhat_enterprise?, :redhat?
-      alias_method :redhat_enterprise_linux?, :redhat?
-      alias_method :redhat_platform?, :redhat?
+      # chef-sugar backcompat method
+      alias_method :redhat_enterprise?, :redhat_platform?
+      # chef-sugar backcompat method
+      alias_method :redhat_enterprise_linux?, :redhat_platform?
+      # chef-sugar backcompat method
+      alias_method :redhat?, :redhat_platform?
 
-      # Determine if the current node is centos.
+      # Determine if the current node is CentOS.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
       #
       # @return [Boolean]
       #
-      def centos?(node = __getnode)
+      def centos_platform?(node = __getnode)
         node["platform"] == "centos"
       end
-      alias_method :centos_platform?, :centos?
+      # chef-sugar backcompat method
+      alias_method :centos?, :centos_platform?
 
-      # Determine if the current node is oracle linux.
+      # Determine if the current node is Oracle Linux.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
       #
       # @return [Boolean]
       #
-      def oracle?(node = __getnode)
+      def oracle_platform?(node = __getnode)
         node["platform"] == "oracle"
       end
-      # chef-sugar backcompat methods
-      alias_method :oracle_linux?, :oracle?
-      alias_method :oracle_platform?, :oracle?
+      # chef-sugar backcompat method
+      alias_method :oracle_linux?, :oracle_platform?
+      # chef-sugar backcompat method
+      alias_method :oracle?, :oracle_platform?
 
-      # Determine if the current node is scientific linux.
+      # Determine if the current node is Scientific Linux.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
       #
       # @return [Boolean]
       #
-      def scientific?(node = __getnode)
+      def scientific_platform?(node = __getnode)
         node["platform"] == "scientific"
       end
-      # chef-sugar backcompat methods
-      alias_method :scientific_linux?, :scientific?
-      alias_method :scientific_platform?, :scientific?
+      # chef-sugar backcompat method
+      alias_method :scientific_linux?, :scientific_platform?
+      # chef-sugar backcompat method
+      alias_method :scientific?, :scientific_platform?
 
-      # Determine if the current node is clearos.
+      # Determine if the current node is ClearOS.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
       #
       # @return [Boolean]
       #
-      def clearos?(node = __getnode)
+      def clearos_platform?(node = __getnode)
         node["platform"] == "clearos"
       end
-      alias_method :clearos_platform?, :clearos?
+      # chef-sugar backcompat method
+      alias_method :clearos?, :clearos_platform?
 
-      # Determine if the current node is fedora.
+      # Determine if the current node is Fedora.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -166,7 +176,7 @@ module ChefUtils
         node["platform"] == "fedora"
       end
 
-      # Determine if the current node is arch
+      # Determine if the current node is Arch Linux
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -177,7 +187,7 @@ module ChefUtils
         node["platform"] == "arch"
       end
 
-      # Determine if the current node is solaris2
+      # Determine if the current node is Solaris2.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -188,7 +198,7 @@ module ChefUtils
         node["platform"] == "solaris2"
       end
 
-      # Determine if the current node is smartos
+      # Determine if the current node is SmartOS.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -199,43 +209,46 @@ module ChefUtils
         node["platform"] == "smartos"
       end
 
-      # Determine if the current node is omnios
+      # Determine if the current node is OmniOS.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
       #
       # @return [Boolean]
       #
-      def omnios?(node = __getnode)
+      def omnios_platform?(node = __getnode)
         node["platform"] == "omnios"
       end
-      alias_method :omnios_platform?, :omnios?
+      # chef-sugar backcompat method
+      alias_method :omnios?, :omnios_platform?
 
-      # Determine if the current node is openindiana
+      # Determine if the current node is OpenIndiana.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
       #
       # @return [Boolean]
       #
-      def openindiana?(node = __getnode)
+      def openindiana_platform?(node = __getnode)
         node["platform"] == "openindiana"
       end
-      alias_method :openindiana_platform?, :openindiana?
+      # chef-sugar backcompat method
+      alias_method :openindiana?, :openindiana_platform?
 
-      # Determine if the current node is nexentacore
+      # Determine if the current node is Nexenta Core Platform aka Nexenta OS.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
       #
       # @return [Boolean]
       #
-      def nexentacore?(node = __getnode)
+      def nexentacore_platform?(node = __getnode)
         node["platform"] == "nexentacore"
       end
-      alias_method :nexentacore_platform?, :nexentacore?
+      # chef-sugar backcompat method
+      alias_method :nexentacore?, :nexentacore_platform?
 
-      # Determine if the current node is aix
+      # Determine if the current node is AIX.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -246,7 +259,7 @@ module ChefUtils
         node["platform"] == "aix"
       end
 
-      # Determine if the current node is freebsd
+      # Determine if the current node is FreeBSD.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -257,7 +270,7 @@ module ChefUtils
         node["platform"] == "freebsd"
       end
 
-      # Determine if the current node is openbsd
+      # Determine if the current node is OpenBSD.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -268,7 +281,7 @@ module ChefUtils
         node["platform"] == "openbsd"
       end
 
-      # Determine if the current node is netbsd
+      # Determine if the current node is NetBSD.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -279,7 +292,7 @@ module ChefUtils
         node["platform"] == "netbsd"
       end
 
-      # Determine if the current node is dragonflybsd
+      # Determine if the current node is DragonFly BSD.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -290,7 +303,7 @@ module ChefUtils
         node["platform"] == "dragonfly"
       end
 
-      # Determine if the current node is MacOS.
+      # Determine if the current node is macOS.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -300,9 +313,10 @@ module ChefUtils
       def macos_platform?(node = __getnode)
         node["platform"] == "mac_os_x"
       end
+      # chef-sugar backcompat method
       alias_method :mac_os_x_platform?, :macos_platform?
 
-      # Determine if the current node is gentoo
+      # Determine if the current node is Gentoo.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -313,7 +327,7 @@ module ChefUtils
         node["platform"] == "gentoo"
       end
 
-      # Determine if the current node is slackware.
+      # Determine if the current node is Slackware.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -335,19 +349,22 @@ module ChefUtils
         node["platform"] == "suse"
       end
 
-      # Determine if the current node is OpenSuSE.
+      # Determine if the current node is OpenSUSE.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
       #
       # @return [Boolean]
       #
-      def opensuse?(node = __getnode)
+      def opensuse_platform?(node = __getnode)
         node["platform"] == "opensuse" || node["platform"] == "opensuseleap"
       end
-      alias_method :opensuse_platform?, :opensuse?
-      alias_method :opensuseleap_platform?, :opensuse?
-      alias_method :leap_platform?, :opensuse?
+      # chef-sugar backcompat method
+      alias_method :opensuse?, :opensuse_platform?
+      # chef-sugar backcompat method
+      alias_method :opensuseleap_platform?, :opensuse_platform?
+      # chef-sugar backcompat method
+      alias_method :leap_platform?, :opensuse_platform?
       # NOTE: to anyone adding :tumbleweed_platform? - :[opensuse]leap_platform? should be false on tumbleweed, :opensuse[_platform]? should be true
 
       # Determine if the current node is Windows.
diff --git a/chef-utils/lib/chef-utils/dsl/platform_family.rb b/chef-utils/lib/chef-utils/dsl/platform_family.rb
index 8efbfd4d4f..9d0c878cb7 100644
--- a/chef-utils/lib/chef-utils/dsl/platform_family.rb
+++ b/chef-utils/lib/chef-utils/dsl/platform_family.rb
@@ -32,7 +32,7 @@ module ChefUtils
       def arch?(node = __getnode)
         node["platform_family"] == "arch"
       end
-      # chef-sugar backcompat methods
+      # chef-sugar backcompat method
       alias_method :arch_linux?, :arch?
 
       # Determine if the current node is a member of the 'aix' platform family.
@@ -78,8 +78,11 @@ module ChefUtils
       def macos?(node = __getnode)
         node["platform_family"] == "mac_os_x"
       end
+      # chef-sugar backcompat method
       alias_method :osx?, :macos?
+      # chef-sugar backcompat method
       alias_method :mac?, :macos?
+      # chef-sugar backcompat method
       alias_method :mac_os_x?, :macos?
 
       # Determine if the current node is a member of the 'rhel' platform family (Red Hat, CentOS, Oracle or Scientific Linux, but NOT Amazon Linux or Fedora).
@@ -92,9 +95,10 @@ module ChefUtils
       def rhel?(node = __getnode)
         node["platform_family"] == "rhel"
       end
+      # chef-sugar backcompat method
       alias_method :el?, :rhel?
 
-      # Determine if the current node is a rhel6 compatible build (Red Hat, CentOS, Oracle or Scientific Linux)
+      # Determine if the current node is a rhel6 compatible build (Red Hat, CentOS, Oracle or Scientific Linux).
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -105,7 +109,7 @@ module ChefUtils
         node["platform_family"] == "rhel" && node["platform_version"].to_f >= 6.0 && node["platform_version"].to_f < 7.0
       end
 
-      # Determine if the current node is a rhel7 compatible build (Red Hat, CentOS, Oracle or Scientific Linux)
+      # Determine if the current node is a rhel7 compatible build (Red Hat, CentOS, Oracle or Scientific Linux).
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -116,7 +120,7 @@ module ChefUtils
         node["platform_family"] == "rhel" && node["platform_version"].to_f >= 7.0 && node["platform_version"].to_f < 8.0
       end
 
-      # Determine if the current node is a rhel8 compatible build (Red Hat, CentOS, Oracle or Scientific Linux)
+      # Determine if the current node is a rhel8 compatible build (Red Hat, CentOS, Oracle or Scientific Linux).
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
@@ -137,6 +141,7 @@ module ChefUtils
       def amazon?(node = __getnode)
         node["platform_family"] == "amazon"
       end
+      # chef-sugar backcompat method
       alias_method :amazon_linux?, :amazon?
 
       # Determine if the current node is a member of the 'solaris2' platform family.
@@ -149,7 +154,7 @@ module ChefUtils
       def solaris2?(node = __getnode)
         node["platform_family"] == "solaris2"
       end
-      # chef-sugar backcompat methods
+      # chef-sugar backcompat method
       alias_method :solaris?, :solaris2?
 
       # Determine if the current node is a member of the 'smartos' platform family.
diff --git a/chef-utils/lib/chef-utils/dsl/platform_version.rb b/chef-utils/lib/chef-utils/dsl/platform_version.rb
index 9d576b797a..3d6269dc42 100644
--- a/chef-utils/lib/chef-utils/dsl/platform_version.rb
+++ b/chef-utils/lib/chef-utils/dsl/platform_version.rb
@@ -25,7 +25,8 @@ module ChefUtils
       # Return the platform_version for the node. Acts like a String
       # but also provides a mechanism for checking version constraints.
       #
-      # @param [Chef::Node] node
+      # @param [Chef::Node] node the node to check
+      # @since 15.8
       #
       # @return [ChefUtils::VersionString]
       #
diff --git a/chef-utils/lib/chef-utils/dsl/service.rb b/chef-utils/lib/chef-utils/dsl/service.rb
index be1ea0708e..2ab44383da 100644
--- a/chef-utils/lib/chef-utils/dsl/service.rb
+++ b/chef-utils/lib/chef-utils/dsl/service.rb
@@ -76,6 +76,15 @@ module ChefUtils
         file_exist?("/sbin/chkconfig")
       end
 
+      #
+      # Returns if a particular service exists for a particular service init system. Init systems may be :initd, :upstart, :etc_rcd, :xinetd, and :systemd. Example: service_script_exist?(:systemd, 'ntpd')
+      #
+      # @param [Symbol] type The type of init system. :initd, :upstart, :xinetd, :etc_rcd, or :systemd
+      # @param [String] script The name of the service
+      # @since 15.5
+      #
+      # @return [Boolean]
+      #
       def service_script_exist?(type, script)
         case type
         when :initd
diff --git a/chef-utils/lib/chef-utils/dsl/virtualization.rb b/chef-utils/lib/chef-utils/dsl/virtualization.rb
index df3a1ac3eb..c699b7e5c0 100644
--- a/chef-utils/lib/chef-utils/dsl/virtualization.rb
+++ b/chef-utils/lib/chef-utils/dsl/virtualization.rb
@@ -25,6 +25,7 @@ module ChefUtils
       # Determine if the current node is a KVM guest.
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #
@@ -35,6 +36,7 @@ module ChefUtils
       # Determine if the current node is a KVM host.
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #
@@ -45,6 +47,7 @@ module ChefUtils
       # Determine if the current node is running in a linux container.
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #
@@ -55,6 +58,7 @@ module ChefUtils
       # Determine if the current node is a linux container host.
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #
@@ -65,6 +69,7 @@ module ChefUtils
       # Determine if the current node is running under Parallels Desktop.
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #   true if the machine is currently running under Parallels Desktop, false
@@ -77,6 +82,7 @@ module ChefUtils
       # Determine if the current node is a Parallels Desktop host.
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #   true if the machine is currently running under Parallels Desktop, false
@@ -89,6 +95,7 @@ module ChefUtils
       # Determine if the current node is a VirtualBox guest.
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #
@@ -99,6 +106,7 @@ module ChefUtils
       # Determine if the current node is a VirtualBox host.
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #
@@ -106,11 +114,13 @@ module ChefUtils
         node.dig("virtualization", "system") == "vbox" && node.dig("virtualization", "role") == "host"
       end
 
+      # chef-sugar backcompat method
       alias_method :virtualbox?, :vbox?
 
       # Determine if the current node is a VMWare guest.
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #
@@ -121,6 +131,7 @@ module ChefUtils
       # Determine if the current node is VMware host.
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #
@@ -131,6 +142,7 @@ module ChefUtils
       # Determine if the current node is an openvz guest.
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #
@@ -141,6 +153,7 @@ module ChefUtils
       # Determine if the current node is an openvz host.
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #
@@ -151,6 +164,7 @@ module ChefUtils
       # Determine if the current node is running under any virutalization environment
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #
@@ -158,11 +172,13 @@ module ChefUtils
         node.dig("virtualization", "role") == "guest"
       end
 
+      # chef-sugar backcompat method
       alias_method :virtual?, :guest?
 
       # Determine if the current node supports running guests under any virtualization environment
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #
@@ -170,9 +186,10 @@ module ChefUtils
         node.dig("virtualization", "role") == "host"
       end
 
-      # Determine if the current node is NOT running under any virtualization environment (plain metal or hypervisor on metal)
+      # Determine if the current node is NOT running under any virtualization environment (bare-metal or hypervisor on metal)
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #
@@ -186,6 +203,7 @@ module ChefUtils
       # vagrantup.com domain in the hostname, which is the best API we have.
       #
       # @param [Chef::Node] node
+      # @since 15.8
       #
       # @return [Boolean]
       #   true if the machine is currently running vagrant, false