Merge pull request #6768 from chef/yard_fixes

Cleanup a bit of YARD and add a few things

11 files changed, 39 insertions, 50 deletions

diff --git a/lib/chef/api_client_v1.rb b/lib/chef/api_client_v1.rb
index a3a5780cc2..7fbff6d6ba 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.
     #
-    # @param [Optional String] The name must be alpha-numeric plus - and _.
+    # @param arg [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.
     #
-    # @param [Optional True/False] Should be true or false - default is false.
+    # @param arg [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.
     #
-    # @param [Optional String] The string representation of the public key.
+    # @param arg [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.
     #
-    # @param [Boolean] whether or not the client is a validator.  If
+    # @param arg [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.
     #
-    # @param [Optional String] The string representation of the private key.
+    # @param arg [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
     #
-    # @param [Optional True/False] Should be true or false - default is false.
+    # @param arg [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(
@@ -200,6 +200,7 @@ class Chef
     end
 
     # Load a client by name via the API
+    # @param name [String] the client name
     def self.load(name)
       response = http_api.get("clients/#{name}")
       Chef::ApiClientV1.from_hash(response)
diff --git a/lib/chef/handler.rb b/lib/chef/handler.rb
index 100ed23d9e..34db223d43 100644
--- a/lib/chef/handler.rb
+++ b/lib/chef/handler.rb
@@ -19,14 +19,12 @@ require "chef/client"
 require "forwardable"
 
 class Chef
-  # == Chef::Handler
   # The base class for an Exception or Notification Handler. Create your own
   # handler by subclassing Chef::Handler. When a Chef run fails with an
   # uncaught Exception, Chef will set the +run_status+ on your handler and call
   # +report+
   #
-  # ===Example:
-  #
+  # @example
   #   require 'net/smtp'
   #
   #   module MyOrg
diff --git a/lib/chef/mixin/api_version_request_handling.rb b/lib/chef/mixin/api_version_request_handling.rb
index b91a1dfe0a..5566addf1d 100644
--- a/lib/chef/mixin/api_version_request_handling.rb
+++ b/lib/chef/mixin/api_version_request_handling.rb
@@ -19,11 +19,9 @@
 class Chef
   module Mixin
     module ApiVersionRequestHandling
-      # Input:
-      # exeception:
-      #   Net::HTTPServerException that may or may not contain the x-ops-server-api-version header
+      # @param exeception [Net::HTTPServerException] may or may not contain the x-ops-server-api-version header
       # supported_client_versions:
-      #  An array of Integers that represent the API versions the client supports.
+      # @param supported_client_versions [Array<Integer>] The API versions the client supports.
       #
       # Output:
       # nil:
diff --git a/lib/chef/mixin/deprecation.rb b/lib/chef/mixin/deprecation.rb
index 14414036e7..6621555585 100644
--- a/lib/chef/mixin/deprecation.rb
+++ b/lib/chef/mixin/deprecation.rb
@@ -23,24 +23,24 @@ class Chef
       @deprecated_constants ||= {}
     end
 
-      # Add a deprecated constant to the Chef::Mixin namespace.
-      # === Arguments
-      # * name: the constant name, as a relative symbol.
-      # * replacement: the constant to return instead.
-      # * message: A message telling the user what to do instead.
-      # === Example:
-      #   deprecate_constant(:RecipeDefinitionDSLCore, Chef::DSL::Recipe, <<-EOM)
-      #     Chef::Mixin::RecipeDefinitionDSLCore is deprecated, use Chef::DSL::Recipe instead.
-      #   EOM
+    # Add a deprecated constant to the Chef::Mixin namespace.
+    #
+    # @param name [Symbol] the constant name, as a relative symbol.
+    # @param replacement [Object] the constant to return instead.
+    # @param message [String] A message telling the user what to do instead.
+    # @example
+    #   deprecate_constant(:RecipeDefinitionDSLCore, Chef::DSL::Recipe, <<-EOM)
+    #     Chef::Mixin::RecipeDefinitionDSLCore is deprecated, use Chef::DSL::Recipe instead.
+    #   EOM
     def self.deprecate_constant(name, replacement, message)
       deprecated_constants[name] = { :replacement => replacement, :message => message }
     end
 
-      # Const missing hook to look up deprecated constants defined with
-      # deprecate_constant. Emits a warning to the logger and returns the
-      # replacement constant. Will call super, most likely causing an exception
-      # for the missing constant, if +name+ is not found in the
-      # deprecated_constants collection.
+    # Const missing hook to look up deprecated constants defined with
+    # deprecate_constant. Emits a warning to the logger and returns the
+    # replacement constant. Will call super, most likely causing an exception
+    # for the missing constant, if +name+ is not found in the
+    # deprecated_constants collection.
     def self.const_missing(name)
       if new_const = deprecated_constants[name]
         Chef::Log.warn(new_const[:message])
diff --git a/lib/chef/mixin/homebrew_user.rb b/lib/chef/mixin/homebrew_user.rb
index 888c1bcbfd..6e32043c77 100644
--- a/lib/chef/mixin/homebrew_user.rb
+++ b/lib/chef/mixin/homebrew_user.rb
@@ -34,6 +34,7 @@ class Chef
       # This tries to find the user to execute brew as.  If a user is provided, that overrides the brew
       # executable user.  It is an error condition if the brew executable owner is root or we cannot find
       # the brew executable.
+      # @param provided_user [String]
       def find_homebrew_uid(provided_user = nil)
         # They could provide us a user name or a UID
         if provided_user
diff --git a/lib/chef/mixin/openssl_helper.rb b/lib/chef/mixin/openssl_helper.rb
index fb2638f0e9..f12a559097 100644
--- a/lib/chef/mixin/openssl_helper.rb
+++ b/lib/chef/mixin/openssl_helper.rb
@@ -17,6 +17,7 @@
 
 class Chef
   module Mixin
+    # various helpers for use with openssl. Currently used by the openssl_* resources
     module OpenSSLHelper
       def self.included(_base)
         require "openssl" unless defined?(::OpenSSL)
diff --git a/lib/chef/mixin/provides.rb b/lib/chef/mixin/provides.rb
index 43a726de8c..ca045d019e 100644
--- a/lib/chef/mixin/provides.rb
+++ b/lib/chef/mixin/provides.rb
@@ -4,7 +4,7 @@ require "chef/mixin/descendants_tracker"
 class Chef
   module Mixin
     module Provides
-      # TODO no longer needed, remove or deprecate?
+      # @todo no longer needed, remove or deprecate?
       include Chef::Mixin::DescendantsTracker
 
       def provides(short_name, opts = {})
@@ -12,7 +12,8 @@ class Chef
       end
 
       # Check whether this resource provides the resource_name DSL for the given
-      # node.  TODO remove this when we stop checking unregistered things.
+      # node.
+      # @todo remove this when we stop checking unregistered things.
       # FIXME: yard with @yield
       def provides?(node, resource)
         raise NotImplementedError, :provides?
diff --git a/lib/chef/mixin/securable.rb b/lib/chef/mixin/securable.rb
index 85c9dea1d4..788b236d94 100644
--- a/lib/chef/mixin/securable.rb
+++ b/lib/chef/mixin/securable.rb
@@ -59,17 +59,14 @@ class Chef
         )
       end
 
-      #==WindowsMacros
       # Defines methods for adding attributes to a chef resource to describe
       # Windows file security metadata.
       #
       # This module is meant to be used to extend a class (instead of
       # `include`-ing). A class is automatically extended with this module when
       # it includes WindowsSecurableAttributes.
-      # --
-      # TODO should this be separated into different files?
+      # @todo should this be separated into different files?
       module WindowsMacros
-        # === rights_attribute
         # "meta-method" for dynamically creating rights attributes on resources.
         #
         # Multiple rights attributes can be declared. This enables resources to
@@ -162,7 +159,6 @@ class Chef
         end
       end
 
-      #==WindowsSecurableAttributes
       # Defines #inherits to describe Windows file security ACLs on the
       # including class
       module WindowsSecurableAttributes
diff --git a/lib/chef/mixin/shell_out.rb b/lib/chef/mixin/shell_out.rb
index b6e4cffe92..57d5be4adc 100644
--- a/lib/chef/mixin/shell_out.rb
+++ b/lib/chef/mixin/shell_out.rb
@@ -131,7 +131,7 @@ class Chef
         cmd
       end
 
-      # Helper for sublcasses to convert an array of string args into a string.  It
+      # Helper for subclasses to convert an array of string args into a string.  It
       # will compact nil or empty strings in the array and will join the array elements
       # with spaces, without introducing any double spaces for nil/empty elements.
       #
@@ -143,7 +143,7 @@ class Chef
         args.flatten.reject { |i| i.nil? || i == "" }.map(&:to_s).join(" ")
       end
 
-      # Helper for sublcasses to reject nil out of an array.  It allows
+      # Helper for subclasses to reject nil out of an array.  It allows
       # using the array form of shell_out (which avoids the need to surround arguments with
       # quote marks to deal with shells).
       #
diff --git a/lib/chef/mixin/template.rb b/lib/chef/mixin/template.rb
index b10e036c4e..bb811aa758 100644
--- a/lib/chef/mixin/template.rb
+++ b/lib/chef/mixin/template.rb
@@ -23,7 +23,6 @@ class Chef
   module Mixin
     module Template
 
-      # == ChefContext
       # ChefContext was previously used to mix behavior into Erubis::Context so
       # that it would be available to templates. This behavior has now moved to
       # TemplateContext, but this module is still mixed in to the
@@ -32,7 +31,6 @@ class Chef
       module ChefContext
       end
 
-      # == TemplateContext
       # TemplateContext is the base context class for all templates in Chef. It
       # defines user-facing extensions to the base Erubis::Context to provide
       # enhanced features. Individual instances of TemplateContext can be
@@ -72,7 +70,7 @@ class Chef
         # @return [String] recipe path
         attr_reader :recipe_path
 
-        # line in the recipe containing the template reosurce, e.g.:
+        # line in the recipe containing the template resource, e.g.:
         #   2
         #
         # @return [String] recipe line
diff --git a/lib/chef/mixin/why_run.rb b/lib/chef/mixin/why_run.rb
index ea62527bdd..b27458feae 100644
--- a/lib/chef/mixin/why_run.rb
+++ b/lib/chef/mixin/why_run.rb
@@ -21,7 +21,6 @@ class Chef
   module Mixin
     module WhyRun
 
-      # ==ConvergeActions
       # ConvergeActions implements the logic for why run. A ConvergeActions
       # object wraps a collection of actions, which consist of a descriptive
       # string and a block/Proc. Actions are executed by calling #converge!
@@ -60,7 +59,6 @@ class Chef
         end
       end
 
-      # == ResourceRequirements
       # ResourceRequirements provides a framework for making assertions about
       # the host system's state. It also provides a mechanism for making
       # assumptions about what the system's state might have been when running
@@ -182,7 +180,7 @@ class Chef
           # will be allowed to continue in both whyrun and non-whyrun
           # mode
           #
-          # With a service resource that requires /etc/init.d/service-name to exist:
+          # @example With a service resource that requires /etc/init.d/service-name to exist:
           #   # in a provider
           #   assert(:start, :restart) do |a|
           #     a.assertion { ::File.exist?("/etc/init.d/service-name") }
@@ -264,8 +262,8 @@ class Chef
         # Define a new Assertion.
         #
         # Takes a list of action names for which the assertion should be made.
-        # ==== Examples:
-        # A File provider that requires the parent directory to exist:
+        #
+        # @example A File provider that requires the parent directory to exist:
         #
         #   assert(:create, :create_if_missing) do |a|
         #     parent_dir = File.basename(@new_resource.path)
@@ -275,7 +273,7 @@ class Chef
         #     a.why_run("assuming parent directory #{parent_dir} would have been previously created"
         #   end
         #
-        # A service provider that requires the init script to exist:
+        # @example A service provider that requires the init script to exist:
         #
         #   assert(:start, :restart) do |a|
         #     a.assertion { ::File.exist?(@new_resource.init_script) }
@@ -286,17 +284,14 @@ class Chef
         #     end
         #   end
         #
-        # A File provider that will error out if you don't have permissions do
-        # delete the file, *even in why run mode*:
-        #
+        # @example A File provider that will error out if you don't have permissions do delete the file, *even in why run mode*:
         #   assert(:delete) do |a|
         #     a.assertion { ::File.writable?(@new_resource.path) }
         #     a.failure_message(Exceptions::InsufficientPrivileges,
         #                       "You don't have sufficient privileges to delete #{@new_resource.path}")
         #   end
         #
-        # A Template provider that will prevent action execution but continue the run in
-        # whyrun mode if the template source is not available.
+        # @example A Template provider that will prevent action execution but continue the run in whyrun mode if the template source is not available.
         #   assert(:create, :create_if_missing) do |a|
         #     a.assertion { File::exist?(@new_resource.source) }
         #     a.failure_message Chef::Exceptions::TemplateError, "Template #{@new_resource.source} could not be found exist."