Merge pull request #6665 from chef/yard2

Add a few more YARD comments to resources

17 files changed, 76 insertions, 43 deletions

diff --git a/lib/chef/api_client.rb b/lib/chef/api_client.rb
index 087de3fdf9..551d9a6035 100644
--- a/lib/chef/api_client.rb
+++ b/lib/chef/api_client.rb
@@ -47,7 +47,7 @@ class Chef
 
     # Gets or sets the client name.
     #
-    # @params [Optional String] The name must be alpha-numeric plus - and _.
+    # @param [Optional String] The name must be alpha-numeric plus - and _.
     # @return [String] The current value of the name.
     def name(arg = nil)
       set_or_return(
@@ -59,7 +59,7 @@ class Chef
 
     # Gets or sets whether this client is an admin.
     #
-    # @params [Optional True/False] Should be true or false - default is false.
+    # @param [Optional True/False] Should be true or false - default is false.
     # @return [True/False] The current value
     def admin(arg = nil)
       set_or_return(
@@ -71,7 +71,7 @@ class Chef
 
     # Gets or sets the public key.
     #
-    # @params [Optional String] The string representation of the public key.
+    # @param [Optional String] The string representation of the public key.
     # @return [String] The current value.
     def public_key(arg = nil)
       set_or_return(
@@ -83,7 +83,7 @@ class Chef
 
     # Gets or sets whether this client is a validator.
     #
-    # @params [Boolean] whether or not the client is a validator.  If
+    # @param [Boolean] whether or not the client is a validator.  If
     #   `nil`, retrieves the already-set value.
     # @return [Boolean] The current value
     def validator(arg = nil)
@@ -96,7 +96,7 @@ class Chef
 
     # Gets or sets the private key.
     #
-    # @params [Optional String] The string representation of the private key.
+    # @param [Optional String] The string representation of the private key.
     # @return [String] The current value.
     def private_key(arg = nil)
       set_or_return(
diff --git a/lib/chef/api_client_v1.rb b/lib/chef/api_client_v1.rb
index a1b9b8317e..a3a5780cc2 100644
--- a/lib/chef/api_client_v1.rb
+++ b/lib/chef/api_client_v1.rb
@@ -70,7 +70,7 @@ class Chef
 
     # Gets or sets the client name.
     #
-    # @params [Optional String] The name must be alpha-numeric plus - and _.
+    # @param [Optional String] The name must be alpha-numeric plus - and _.
     # @return [String] The current value of the name.
     def name(arg = nil)
       set_or_return(
@@ -82,7 +82,7 @@ class Chef
 
     # Gets or sets whether this client is an admin.
     #
-    # @params [Optional True/False] Should be true or false - default is false.
+    # @param [Optional True/False] Should be true or false - default is false.
     # @return [True/False] The current value
     def admin(arg = nil)
       set_or_return(
@@ -94,7 +94,7 @@ class Chef
 
     # Gets or sets the public key.
     #
-    # @params [Optional String] The string representation of the public key.
+    # @param [Optional String] The string representation of the public key.
     # @return [String] The current value.
     def public_key(arg = nil)
       set_or_return(
@@ -106,7 +106,7 @@ class Chef
 
     # Gets or sets whether this client is a validator.
     #
-    # @params [Boolean] whether or not the client is a validator.  If
+    # @param [Boolean] whether or not the client is a validator.  If
     #   `nil`, retrieves the already-set value.
     # @return [Boolean] The current value
     def validator(arg = nil)
@@ -120,7 +120,7 @@ class Chef
     # Private key. The server will return it as a string.
     # Set to true under API V0 to have the server regenerate the default key.
     #
-    # @params [Optional String] The string representation of the private key.
+    # @param [Optional String] The string representation of the private key.
     # @return [String] The current value.
     def private_key(arg = nil)
       set_or_return(
@@ -132,7 +132,7 @@ class Chef
 
     # Used to ask server to generate key pair under api V1
     #
-    # @params [Optional True/False] Should be true or false - default is false.
+    # @param [Optional True/False] Should be true or false - default is false.
     # @return [True/False] The current value
     def create_key(arg = nil)
       set_or_return(
diff --git a/lib/chef/chef_class.rb b/lib/chef/chef_class.rb
index e61fd5e1d2..bfea51609a 100644
--- a/lib/chef/chef_class.rb
+++ b/lib/chef/chef_class.rb
@@ -200,8 +200,8 @@ class Chef
     #
     # Emit a deprecation message.
     #
-    # @param type The message to send. This should be a symbol, referring to
-    #   a class defined in Chef::Deprecated
+    # @param [Symbol] type The message to send. This should refer to a class
+    #   defined in Chef::Deprecated
     # @param message  An explicit message to display, rather than the generic one
     #   associated with the deprecation.
     # @param location The location. Defaults to the caller who called you (since
diff --git a/lib/chef/chef_fs/data_handler/data_handler_base.rb b/lib/chef/chef_fs/data_handler/data_handler_base.rb
index 3668f77dd5..4b4696ce5e 100644
--- a/lib/chef/chef_fs/data_handler/data_handler_base.rb
+++ b/lib/chef/chef_fs/data_handler/data_handler_base.rb
@@ -56,8 +56,7 @@ class Chef
         # 2. Put the actual values in the order of the defaults
         # 3. Move any other values to the end
         #
-        # == Example
-        #
+        # @example
         #   normalize_hash({x: 100, c: 2, a: 1}, { a: 10, b: 20, c: 30})
         #   -> { a: 1, b: 20, c: 2, x: 100}
         #
@@ -140,8 +139,7 @@ class Chef
         # the keys specified in "keys"; anything else must be emitted by the
         # caller.
         #
-        # == Example
-        #
+        # @example
         #   to_ruby_keys({"name" => "foo", "environment" => "desert", "foo": "bar"}, [ "name", "environment" ])
         #   ->
         #   'name "foo"
diff --git a/lib/chef/cookbook/chefignore.rb b/lib/chef/cookbook/chefignore.rb
index dce58ecdb8..a27af68cb0 100644
--- a/lib/chef/cookbook/chefignore.rb
+++ b/lib/chef/cookbook/chefignore.rb
@@ -33,12 +33,16 @@ class Chef
         @ignores = parse_ignore_file
       end
 
+      # @param [Array] list the list of cookbook files
+      # @return [Array] list of cookbook files with chefignore files removed
       def remove_ignores_from(file_list)
         Array(file_list).inject([]) do |unignored, file|
           ignored?(file) ? unignored : unignored << file
         end
       end
 
+      # @param [String] file_name the file name to check ignored status for
+      # @return [Boolean] is the file ignored or not
       def ignored?(file_name)
         @ignores.any? { |glob| File.fnmatch?(glob, file_name) }
       end
diff --git a/lib/chef/cookbook/cookbook_collection.rb b/lib/chef/cookbook/cookbook_collection.rb
index d06b8fd042..997eb6de12 100644
--- a/lib/chef/cookbook/cookbook_collection.rb
+++ b/lib/chef/cookbook/cookbook_collection.rb
@@ -47,8 +47,8 @@ class Chef
     # Currently checks chef_version and ohai_version in the cookbook metadata
     # against the running Chef::VERSION and Ohai::VERSION.
     #
-    # @raises [Chef::Exceptions::CookbookChefVersionMismatch] if the Chef::VERSION fails validation
-    # @raises [Chef::Exceptions::CookbookOhaiVersionMismatch] if the Ohai::VERSION fails validation
+    # @raise [Chef::Exceptions::CookbookChefVersionMismatch] if the Chef::VERSION fails validation
+    # @raise [Chef::Exceptions::CookbookOhaiVersionMismatch] if the Ohai::VERSION fails validation
     def validate!
       each do |cookbook_name, cookbook_version|
         cookbook_version.metadata.validate_chef_version!
diff --git a/lib/chef/cookbook/metadata.rb b/lib/chef/cookbook/metadata.rb
index b23c01e622..a6bb3d079d 100644
--- a/lib/chef/cookbook/metadata.rb
+++ b/lib/chef/cookbook/metadata.rb
@@ -596,7 +596,7 @@ class Chef
       # Validates that the Ohai::VERSION of the running chef-client matches one of the
       # configured ohai_version statements in this cookbooks metadata.
       #
-      # @raises [Chef::Exceptions::CookbookOhaiVersionMismatch] if the cookbook fails validation
+      # @raise [Chef::Exceptions::CookbookOhaiVersionMismatch] if the cookbook fails validation
       def validate_ohai_version!
         unless gem_dep_matches?("ohai", Gem::Version.new(Ohai::VERSION), *ohai_versions)
           raise Exceptions::CookbookOhaiVersionMismatch.new(Ohai::VERSION, name, version, *ohai_versions)
@@ -606,7 +606,7 @@ class Chef
       # Validates that the Chef::VERSION of the running chef-client matches one of the
       # configured chef_version statements in this cookbooks metadata.
       #
-      # @raises [Chef::Exceptions::CookbookChefVersionMismatch] if the cookbook fails validation
+      # @raise [Chef::Exceptions::CookbookChefVersionMismatch] if the cookbook fails validation
       def validate_chef_version!
         unless gem_dep_matches?("chef", Gem::Version.new(Chef::VERSION), *chef_versions)
           raise Exceptions::CookbookChefVersionMismatch.new(Chef::VERSION, name, version, *chef_versions)
diff --git a/lib/chef/knife.rb b/lib/chef/knife.rb
index aa30f2e2ed..65d687af70 100644
--- a/lib/chef/knife.rb
+++ b/lib/chef/knife.rb
@@ -42,9 +42,9 @@ class Chef
     extend Chef::Mixin::ConvertToClassName
     extend Forwardable
 
-    # Backwards Compat:
-    # Ideally, we should not vomit all of these methods into this base class;
-    # instead, they should be accessed by hitting the ui object directly.
+    # @note Backwards Compat:
+    #   Ideally, we should not vomit all of these methods into this base class;
+    #   instead, they should be accessed by hitting the ui object directly.
     def_delegator :@ui, :stdout
     def_delegator :@ui, :stderr
     def_delegator :@ui, :stdin
@@ -105,12 +105,11 @@ class Chef
     # Explicitly set the category for the current command to +new_category+
     # The category is normally determined from the first word of the command
     # name, but some commands make more sense using two or more words
-    # ===Arguments
-    # new_category::: A String to set the category to (see examples)
-    # ===Examples:
-    # Data bag commands would be in the 'data' category by default. To put them
-    # in the 'data bag' category:
-    #   category('data bag')
+    # @param new_category [String] value to set the category to (see examples)
+    #
+    # @example Data bag commands would be in the 'data' category by default. To
+    #  put them in the 'data bag' category:
+    #  category('data bag')
     def self.category(new_category)
       @category = new_category
     end
@@ -196,10 +195,11 @@ class Chef
 
     # Run knife for the given +args+ (ARGV), adding +options+ to the list of
     # CLI options that the subcommand knows how to handle.
-    # ===Arguments
-    # args::: usually ARGV
-    # options::: A Mixlib::CLI option parser hash. These +options+ are how
-    # subcommands know about global knife CLI options
+    #
+    # @param args [Array] The arguments. Usually ARGV
+    # @param options [Mixlib::CLI option parser hash] These +options+ are how
+    #   subcommands know about global knife CLI options
+    #
     def self.run(args, options = {})
       # Fallback debug logging. Normally the logger isn't configured until we
       # read the config, but this means any logging that happens before the
diff --git a/lib/chef/knife/data_bag_secret_options.rb b/lib/chef/knife/data_bag_secret_options.rb
index 4246c9edfa..a612004e15 100644
--- a/lib/chef/knife/data_bag_secret_options.rb
+++ b/lib/chef/knife/data_bag_secret_options.rb
@@ -95,7 +95,7 @@ class Chef
 
       ##
       # Determine if the user has specified an appropriate secret for encrypting data bag items.
-      # @returns boolean
+      # @return boolean
       def base_encryption_secret_provided?(need_encrypt_flag = true)
         validate_secrets
 
diff --git a/lib/chef/mixin/powershell_out.rb b/lib/chef/mixin/powershell_out.rb
index ab7cf00a72..1a757074c2 100644
--- a/lib/chef/mixin/powershell_out.rb
+++ b/lib/chef/mixin/powershell_out.rb
@@ -74,7 +74,7 @@ class Chef
       # Helper to build a powershell command around the script to run.
       #
       # @param script [String] script to run
-      # @retrurn [String] powershell command to execute
+      # @return [String] powershell command to execute
       def build_powershell_command(script)
         flags = [
           # Hides the copyright banner at startup.
diff --git a/lib/chef/provider/package/dnf.rb b/lib/chef/provider/package/dnf.rb
index 7843bc74fc..90a5596727 100644
--- a/lib/chef/provider/package/dnf.rb
+++ b/lib/chef/provider/package/dnf.rb
@@ -148,7 +148,7 @@ class Chef
           @available_version[index]
         end
 
-        # @returns Array<Version>
+        # @return [Array<Version>]
         def installed_version(index)
           @installed_version ||= []
           @installed_version[index] ||= if new_resource.source
diff --git a/lib/chef/provider/remote_directory.rb b/lib/chef/provider/remote_directory.rb
index 6f4956de96..a9edf5fa58 100644
--- a/lib/chef/provider/remote_directory.rb
+++ b/lib/chef/provider/remote_directory.rb
@@ -153,7 +153,7 @@ class Chef
       #
       # FIXME: it should do breadth-first, see CHEF-5080 (please use a performant sort)
       #
-      # @return Array<String> The list of files to transfer
+      # @return [Array<String>] The list of files to transfer
       # @api private
       #
       def files_to_transfer
diff --git a/lib/chef/resource/chef_gem.rb b/lib/chef/resource/chef_gem.rb
index 7025d74e58..3a2d90e852 100644
--- a/lib/chef/resource/chef_gem.rb
+++ b/lib/chef/resource/chef_gem.rb
@@ -30,6 +30,7 @@ class Chef
                }
       property :compile_time, [ true, false ], default: false, desired_state: false
 
+      # force the resource to compile time if the compile time property has been set
       def after_created
         if compile_time
           Array(action).each do |action|
diff --git a/lib/chef/resource/file.rb b/lib/chef/resource/file.rb
index 5c275a574f..0540385646 100644
--- a/lib/chef/resource/file.rb
+++ b/lib/chef/resource/file.rb
@@ -43,7 +43,7 @@ class Chef
       # mutate the new_resource.checksum which would change the
       # user intent in the new_resource if the resource is reused.
       #
-      # @returns [String] Checksum of the file we actually rendered
+      # @return [String] Checksum of the file we actually rendered
       attr_accessor :final_checksum
 
       default_action :create
diff --git a/lib/chef/resource/freebsd_package.rb b/lib/chef/resource/freebsd_package.rb
index ecaff95244..eedddf28e7 100644
--- a/lib/chef/resource/freebsd_package.rb
+++ b/lib/chef/resource/freebsd_package.rb
@@ -32,19 +32,26 @@ class Chef
       resource_name :freebsd_package
       provides :package, platform: "freebsd"
 
+      # make sure we assign the appropriate underlying providers based on what
+      # package managers exist on this FreeBSD system or the source of the package
+      #
+      # @return [void]
       def after_created
         assign_provider
       end
 
+      # Is the system at least version 1000017 or is the make variable WITH_PKGNG set
+      #
+      # @return [Boolean] do we support pkgng
       def supports_pkgng?
         ships_with_pkgng? || !!shell_out_compact!("make", "-V", "WITH_PKGNG", :env => nil).stdout.match(/yes/i)
       end
 
       private
 
+      # It was not until __FreeBSD_version 1000017 that pkgng became
+      # the default binary package manager. See '/usr/ports/Mk/bsd.port.mk'.
       def ships_with_pkgng?
-        # It was not until __FreeBSD_version 1000017 that pkgng became
-        # the default binary package manager. See '/usr/ports/Mk/bsd.port.mk'.
         node[:os_version].to_i >= 1000017
       end
 
diff --git a/lib/chef/resource/resource_notification.rb b/lib/chef/resource/resource_notification.rb
index ee90064a17..bd09097669 100644
--- a/lib/chef/resource/resource_notification.rb
+++ b/lib/chef/resource/resource_notification.rb
@@ -20,6 +20,10 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # @author Tyler Ball
+    # @attr [Resource] resource the Chef resource object to notify to
+    # @attr [Action] action the action to notify
+    # @attr [Resource] notifying_resource the Chef resource performing the notification
     class Notification
 
       attr_accessor :resource, :action, :notifying_resource
@@ -30,6 +34,10 @@ class Chef
         @notifying_resource = notifying_resource
       end
 
+      # Is the current notification a duplicate of another notification
+      #
+      # @param [Notification] another notification object to compare to
+      # @return [Boolean] does the resource match
       def duplicates?(other_notification)
         unless other_notification.respond_to?(:resource) && other_notification.respond_to?(:action)
           msg = "only duck-types of Chef::Resource::Notification can be checked for duplication "\
@@ -41,6 +49,9 @@ class Chef
 
       # If resource and/or notifying_resource is not a resource object, this will look them up in the resource collection
       # and fix the references from strings to actual Resource objects.
+      # @param [ResourceCollection] resource_collection
+      #
+      # @return [void]
       def resolve_resource_reference(resource_collection)
         return resource if resource.kind_of?(Chef::Resource) && notifying_resource.kind_of?(Chef::Resource)
 
@@ -55,6 +66,9 @@ class Chef
 
       # This will look up the resource if it is not a Resource Object.  It will complain if it finds multiple
       # resources, can't find a resource, or gets invalid syntax.
+      # @param [ResourceCollection] resource_collection
+      #
+      # @return [void]
       def fix_resource_reference(resource_collection)
         matching_resource = resource_collection.find(resource)
         if Array(matching_resource).size > 1
@@ -84,6 +98,9 @@ is defined near #{notifying_resource.source_line}
 
       # This will look up the notifying_resource if it is not a Resource Object.  It will complain if it finds multiple
       # resources, can't find a resource, or gets invalid syntax.
+      # @param [ResourceCollection] resource_collection
+      #
+      # @return [void]
       def fix_notifier_reference(resource_collection)
         matching_notifier = resource_collection.find(notifying_resource)
         if Array(matching_notifier).size > 1
diff --git a/lib/chef/run_context.rb b/lib/chef/run_context.rb
index fc32ab3eeb..b2eee0406e 100644
--- a/lib/chef/run_context.rb
+++ b/lib/chef/run_context.rb
@@ -29,7 +29,6 @@ require "forwardable"
 
 class Chef
 
-  # == Chef::RunContext
   # Value object that loads and tracks the context of a Chef run
   class RunContext
     #
@@ -312,7 +311,7 @@ class Chef
     #
     # @param recipe_names [Array[String]] The recipe name (e.g 'my_cookbook' or
     #   'my_cookbook::my_resource').
-    # @param current_cookbook The cookbook we are currently running in.
+    # @param current_cookbook [String] The cookbook we are currently running in.
     #
     # @return A truthy value if the load occurred; `false` if already loaded.
     #
@@ -556,11 +555,18 @@ ERROR_MESSAGE
       @reboot_info = reboot_info
     end
 
+    #
+    # Cancels a pending reboot
+    #
     def cancel_reboot
       Chef::Log.info "Changing reboot status from #{reboot_info.inspect} to {}"
       @reboot_info = {}
     end
 
+    #
+    # Checks to see if a reboot has been requested
+    # @return [Boolean]
+    #
     def reboot_requested?
       reboot_info.size > 0
     end