From af4ba14f511780ce55737aec2d346d0bf1afb962 Mon Sep 17 00:00:00 2001 From: Tim Smith Date: Mon, 11 Mar 2019 16:27:27 -0700 Subject: Add misc YARD comments A pile of misc yard I added as I was reading things. Signed-off-by: Tim Smith --- lib/chef/knife/bootstrap.rb | 1 + lib/chef/provider.rb | 23 +++++++++++++++++------ lib/chef/resource/build_essential.rb | 3 ++- lib/chef/resource/chef_gem.rb | 2 ++ lib/chef/resource/chef_handler.rb | 3 +++ lib/chef/resource/execute.rb | 3 +++ lib/chef/resource/homebrew_cask.rb | 3 +++ lib/chef/resource/homebrew_tap.rb | 3 +++ lib/chef/resource/hostname.rb | 2 ++ lib/chef/resource/link.rb | 5 ++--- lib/chef/resource/ohai_hint.rb | 2 ++ 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| -- cgit v1.2.1