Add misc YARD commentsyard3

A pile of misc yard I added as I was reading things.

Signed-off-by: Tim Smith <tsmith@chef.io>

11 files changed, 40 insertions, 10 deletions

diff --git a/lib/chef/knife/bootstrap.rb b/lib/chef/knife/bootstrap.rb
index 19ae78cff5..b9e09a15ba 100644
--- a/lib/chef/knife/bootstrap.rb
+++ b/lib/chef/knife/bootstrap.rb
@@ -395,6 +395,7 @@ class Chef
         end
       end
 
+      # fail if the server_name is nil
       def validate_name_args!
         if server_name.nil?
           ui.error("Must pass an FQDN or ip to bootstrap")
diff --git a/lib/chef/provider.rb b/lib/chef/provider.rb
index 1751c35129..fb4ac9f659 100644
--- a/lib/chef/provider.rb
+++ b/lib/chef/provider.rb
@@ -59,6 +59,7 @@ class Chef
     # @since 13.0
     # @param name [String, Symbol] Name of the action to define.
     # @param block [Proc] Body of the action.
+    #
     # @return [void]
     def self.action(name, &block)
       # We need the block directly in a method so that `super` works.
@@ -82,11 +83,10 @@ class Chef
     #
     def_delegators :@new_resource, :property_is_set?
 
-    #--
-    # TODO: this should be a reader, and the action should be passed in the
+    # @todo this should be a reader, and the action should be passed in the
     # constructor; however, many/most subclasses override the constructor so
     # changing the arity would be a breaking change. Change this at the next
-    # break, e.g., Chef 11.
+    # major release
     attr_accessor :action
 
     def initialize(new_resource, run_context)
@@ -107,10 +107,17 @@ class Chef
       self.class.include_resource_dsl_module(new_resource)
     end
 
+    # has why-run mode been enabled?
+    #
+    # @return [Boolean]
     def whyrun_mode?
       Chef::Config[:why_run]
     end
 
+    # as of Chef 13 we enable why-run by default and require resources to override this to set false.
+    # We're keeping this method to prevent breaking the cookbook world for no real gain on our part.
+    #
+    # @return [Boolean]
     def whyrun_supported?
       true
     end
@@ -131,6 +138,8 @@ class Chef
     def check_resource_semantics!
     end
 
+    # a simple placeholder method that will be called / raise if a resource tries to
+    # use current_resource without defining a load_current_resource method.
     def load_current_resource
       raise Chef::Exceptions::Override, "You must override load_current_resource in #{self}"
     end
@@ -141,6 +150,7 @@ class Chef
     def cleanup_after_converge
     end
 
+    # the :nothing action which is available on all resources by default
     def action_nothing
       logger.trace("Doing nothing for #{@new_resource}")
       true
@@ -153,9 +163,7 @@ class Chef
     def run_action(action = nil)
       @action = action unless action.nil?
 
-      # TODO: it would be preferable to get the action to be executed in the
-      # constructor...
-
+      # @todo it would be preferable to get the action to be executed in the constructor...
       check_resource_semantics!
 
       # user-defined LWRPs may include unsafe load_current_resource methods that cannot be run in whyrun mode
@@ -372,6 +380,9 @@ class Chef
 
     protected
 
+    # stores all actions that have been converged
+    #
+    # @return [ConvergeActions]
     def converge_actions
       @converge_actions ||= ConvergeActions.new(@new_resource, run_context, @action)
     end
diff --git a/lib/chef/resource/build_essential.rb b/lib/chef/resource/build_essential.rb
index c10be4b6a1..e9cb656ca6 100644
--- a/lib/chef/resource/build_essential.rb
+++ b/lib/chef/resource/build_essential.rb
@@ -121,7 +121,6 @@ class Chef
         # Determine if the XCode Command Line Tools are installed
         #
         # @return [true, false]
-        #
         def xcode_cli_installed?
           cmd = Mixlib::ShellOut.new("pkgutil --pkgs=com.apple.pkg.CLTools_Executables")
           cmd.run_command
@@ -131,6 +130,8 @@ class Chef
       end
 
       # this resource forces itself to run at compile_time
+      #
+      # @return [void]
       def after_created
         return unless compile_time
         Array(action).each do |action|
diff --git a/lib/chef/resource/chef_gem.rb b/lib/chef/resource/chef_gem.rb
index 6758a0c753..2079e5d796 100644
--- a/lib/chef/resource/chef_gem.rb
+++ b/lib/chef/resource/chef_gem.rb
@@ -46,6 +46,8 @@ class Chef
                default: false, desired_state: false
 
       # force the resource to compile time if the compile time property has been set
+      #
+      # @return [void]
       def after_created
         if compile_time
           Array(action).each do |action|
diff --git a/lib/chef/resource/chef_handler.rb b/lib/chef/resource/chef_handler.rb
index 6d55f882bd..2bac109697 100644
--- a/lib/chef/resource/chef_handler.rb
+++ b/lib/chef/resource/chef_handler.rb
@@ -92,6 +92,8 @@ class Chef
         #
         # @param handler_type [Symbol] such as :report or :exception.
         # @param class_full_name [String] such as 'Chef::Handler::ErrorReport'.
+        #
+        # @return [void]
         def unregister_handler(handler_type, class_full_name)
           Chef::Config.send("#{handler_type}_handlers").delete_if do |v|
             # avoid a bit of log spam
@@ -106,6 +108,7 @@ class Chef
         # If the class is not available, NameError is thrown.
         #
         # @param class_full_name [String] full class name such as 'Chef::Handler::Foo' or 'MyHandler'.
+        #
         # @return [Array] parent class and child class.
         def get_class(class_full_name)
           ancestors = class_full_name.split("::")
diff --git a/lib/chef/resource/execute.rb b/lib/chef/resource/execute.rb
index 3f4b74bd96..afab9a7b27 100644
--- a/lib/chef/resource/execute.rb
+++ b/lib/chef/resource/execute.rb
@@ -116,6 +116,9 @@ class Chef
         ancestor_attributes.concat(@class_inherited_attributes ? @class_inherited_attributes : []).uniq
       end
 
+      # post resource creation validation
+      #
+      # @return [void]
       def after_created
         validate_identity_platform(user, password, domain, elevated)
         identity = qualify_user(user, password, domain)
diff --git a/lib/chef/resource/homebrew_cask.rb b/lib/chef/resource/homebrew_cask.rb
index 264ad72587..1f5a9afa81 100644
--- a/lib/chef/resource/homebrew_cask.rb
+++ b/lib/chef/resource/homebrew_cask.rb
@@ -87,6 +87,9 @@ class Chef
         alias_method :action_uncask, :action_remove
         alias_method :action_uninstall, :action_remove
 
+        # Is the desired cask already casked?
+        #
+        # @return [Boolean]
         def casked?
           unscoped_name = new_resource.cask_name.split("/").last
           shell_out!("#{new_resource.homebrew_path} cask list 2>/dev/null",
diff --git a/lib/chef/resource/homebrew_tap.rb b/lib/chef/resource/homebrew_tap.rb
index 9d880c565f..bbcc0b1463 100644
--- a/lib/chef/resource/homebrew_tap.rb
+++ b/lib/chef/resource/homebrew_tap.rb
@@ -78,6 +78,9 @@ class Chef
         end
       end
 
+      # Is the passed tap already tapped
+      #
+      # @return [Boolean]
       def tapped?(name)
         tap_dir = name.gsub("/", "/homebrew-")
         ::File.directory?("/usr/local/Homebrew/Library/Taps/#{tap_dir}")
diff --git a/lib/chef/resource/hostname.rb b/lib/chef/resource/hostname.rb
index 6b5a5617cf..d0bf9b9a4b 100644
--- a/lib/chef/resource/hostname.rb
+++ b/lib/chef/resource/hostname.rb
@@ -253,6 +253,8 @@ class Chef
       end
 
       # this resource forces itself to run at compile_time
+      #
+      # @return [void]
       def after_created
         if compile_time
           Array(action).each do |action|
diff --git a/lib/chef/resource/link.rb b/lib/chef/resource/link.rb
index f62209108c..adb8e10533 100644
--- a/lib/chef/resource/link.rb
+++ b/lib/chef/resource/link.rb
@@ -74,10 +74,9 @@ class Chef
 
       private
 
+      # On certain versions of windows links are not supported. Make
+      # sure we are not on such a platform.
       def verify_links_supported!
-        # On certain versions of windows links are not supported. Make
-        # sure we are not on such a platform.
-
         if Chef::Platform.windows?
           require "chef/win32/file"
           begin
diff --git a/lib/chef/resource/ohai_hint.rb b/lib/chef/resource/ohai_hint.rb
index 0a710a166c..e8de5f602a 100644
--- a/lib/chef/resource/ohai_hint.rb
+++ b/lib/chef/resource/ohai_hint.rb
@@ -84,6 +84,8 @@ class Chef
       end
 
       # this resource forces itself to run at compile_time
+      #
+      # @return [void]
       def after_created
         return unless compile_time
         Array(action).each do |action|