From be8540a076226051029dc161895bc887eb4813b1 Mon Sep 17 00:00:00 2001 From: Tim Smith Date: Wed, 13 Dec 2017 12:14:25 -0800 Subject: Cleanup some YARD warnings Signed-off-by: Tim Smith --- lib/chef/api_client.rb | 10 ++++----- lib/chef/api_client_v1.rb | 12 +++++----- lib/chef/chef_class.rb | 4 ++-- lib/chef/chef_fs/data_handler/data_handler_base.rb | 6 ++--- lib/chef/cookbook/chefignore.rb | 4 ++++ lib/chef/cookbook/cookbook_collection.rb | 4 ++-- lib/chef/cookbook/metadata.rb | 4 ++-- lib/chef/knife.rb | 26 +++++++++++----------- lib/chef/knife/data_bag_secret_options.rb | 2 +- lib/chef/mixin/powershell_out.rb | 2 +- lib/chef/provider/package/dnf.rb | 2 +- lib/chef/provider/remote_directory.rb | 2 +- lib/chef/resource/file.rb | 2 +- lib/chef/run_context.rb | 10 +++++++-- 14 files changed, 49 insertions(+), 41 deletions(-) (limited to 'lib/chef') 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 + # @return [Array] 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 The list of files to transfer + # @return [Array] The list of files to transfer # @api private # def files_to_transfer 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/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 -- cgit v1.2.1