Merge pull request #1187 from chef/comments

Fix yard parsing issues & add more commments

13 files changed, 120 insertions, 40 deletions

diff --git a/lib/ohai/common/dmi.rb b/lib/ohai/common/dmi.rb
index 3403bd93..3316f810 100644
--- a/lib/ohai/common/dmi.rb
+++ b/lib/ohai/common/dmi.rb
@@ -76,7 +76,10 @@ module Ohai
       # away some of the less useful IDs
       ID_TO_CAPTURE = [ 0, 1, 2, 3, 4, 6, 11 ]
 
-      # return the list of DMI IDs to capture
+      # the whitelisted DMI IDs. This is combination of the defaults + any additional
+      # IDs defined in the :additional_dmi_ids config
+      #
+      # @return [Array] the list of DMI IDs to capture
       def whitelisted_ids
         if Ohai.config[:additional_dmi_ids]
           if [ Integer, Array ].include?(Ohai.config[:additional_dmi_ids].class)
@@ -88,7 +91,11 @@ module Ohai
         ID_TO_CAPTURE
       end
 
-      # look up DMI ID
+      # the human readable description from a DMI ID
+      #
+      # @param id [String, Integer] the ID to lookup
+      #
+      # @return [String]
       def id_lookup(id)
         id = id.to_i
         if (id >= 128) && (id <= 255)
diff --git a/lib/ohai/dsl/plugin.rb b/lib/ohai/dsl/plugin.rb
index 13fc4202..cea98f86 100644
--- a/lib/ohai/dsl/plugin.rb
+++ b/lib/ohai/dsl/plugin.rb
@@ -28,10 +28,16 @@ module Ohai
 
   # For plugin namespacing
   module NamedPlugin
+
+    # Is the plugin a Symbol starting with a capital letter that has no underscores
+    #
+    # @param name [String] the plugin name
+    # @return [Boolean]
     def self.valid_name?(name)
       name.is_a?(Symbol) && name.to_s.match(/^[^A-Z]|_/).nil?
     end
 
+    # @return [Boolean]
     def self.strict_const_defined?(const)
       const_defined?(const, false)
     end
diff --git a/lib/ohai/dsl/plugin/versionvii.rb b/lib/ohai/dsl/plugin/versionvii.rb
index 06e0e0d7..d54920e2 100644
--- a/lib/ohai/dsl/plugin/versionvii.rb
+++ b/lib/ohai/dsl/plugin/versionvii.rb
@@ -20,6 +20,8 @@
 module Ohai
   module DSL
     class Plugin
+      # The class for the "Version 7" plugin format we introduced in Ohai 7. This is the 2nd
+      # generation of Ohai plugin and the previous generation (V6) was removed in Ohai 14
       class VersionVII < Plugin
         attr_reader :version
         attr_reader :source
@@ -30,14 +32,23 @@ module Ohai
           @version = :version7
         end
 
+        # the plugin name we use through Ohai (Foo) vs. the class name (Ohai::NamedPlugin::Foo)
+        #
+        # @return [String]
         def name
           self.class.name.split("Ohai::NamedPlugin::")[1].to_sym
         end
 
+        # return that we're a v7 plugin
+        #
+        # @return [Symbol]
         def self.version
           :version7
         end
 
+        # the source of the plugin on disk. This is an array since a plugin may exist for multiple platforms and this would include each of those platform specific file paths
+        #
+        # @return [Array]
         def self.sources
           @source_list ||= []
         end
@@ -50,30 +61,51 @@ module Ohai
           @depends_attrs ||= []
         end
 
+        # A block per platform for actually performing data collection constructed
+        # by the collect_data method
+        #
+        # @return [Mash]
         def self.data_collector
           @data_collector ||= Mash.new
         end
 
+        # set the attributes provided by the plugin
+        #
+        # @param attrs [Array]
         def self.provides(*attrs)
           attrs.each do |attr|
             provides_attrs << attr unless provides_attrs.include?(attr)
           end
         end
 
+        # set the attributes depended on by the plugin
+        #
+        # @param attrs [Array]
         def self.depends(*attrs)
           attrs.each do |attr|
             depends_attrs << attr unless depends_attrs.include?(attr)
           end
         end
 
+        # set the plugin optional state
+        #
+        # @param opt [Boolean]
         def self.optional(opt = true)
           @optional = opt
         end
 
+        # check if the plugin is optional
+        #
+        # @return [Boolean]
         def self.optional?
           !!@optional
         end
 
+        # define data collection methodology per platform
+        #
+        # @param platform [Symbol] the platform to collect data for
+        # @param other_platforms [Array] additional platforms to collect data for
+        # @param block [block] the actual code to collect data for the specified platforms
         def self.collect_data(platform = :default, *other_platforms, &block)
           [platform, other_platforms].flatten.each do |plat|
             if data_collector.has_key?(plat)
@@ -84,6 +116,7 @@ module Ohai
           end
         end
 
+        # @return [Array]
         def dependencies
           self.class.depends_attrs
         end
diff --git a/lib/ohai/hints.rb b/lib/ohai/hints.rb
index bfe77f69..a3501ea0 100644
--- a/lib/ohai/hints.rb
+++ b/lib/ohai/hints.rb
@@ -21,10 +21,14 @@ require "ffi_yajl"
 
 module Ohai
   module Hints
+    # clear out any known hints in the @hints variable
     def self.refresh_hints
       @hints = {}
     end
 
+    # parse the JSON conents of a hint file. Return an empty hash if the file has
+    # no JSON content
+    # @param filename [String] the hint file path
     def self.parse_hint_file(filename)
       json_parser = FFI_Yajl::Parser.new
       hash = json_parser.parse(File.read(filename))
@@ -35,6 +39,10 @@ module Ohai
       Ohai::Log.error("Could not parse hint file at #{filename}: #{e.message}")
     end
 
+    # retrieve hint contents given a hint name. Looks up in @hints variable first. Attempts
+    # to load from file in config's :hints_path if not already cached. Saves the contents
+    # to the hash if the file was successfully parsed
+    # @param name [String] the name of the hint (not the path)
     def self.hint?(name)
       @hints ||= {}
       return @hints[name] if @hints[name]
diff --git a/lib/ohai/mash.rb b/lib/ohai/mash.rb
index 5ea21d76..f6c25db5 100644
--- a/lib/ohai/mash.rb
+++ b/lib/ohai/mash.rb
@@ -50,12 +50,9 @@
 # params[:key] instead of params['key'].
 class Mash < Hash
 
-  # @param constructor<Object>
-  #   The default value for the mash. Defaults to an empty hash.
-  #
-  # @details [Alternatives]
-  #   If constructor is a Hash, a new mash will be created based on the keys of
-  #   the hash and no default value will be set.
+  # @param constructor [Object] The default value for the mash.
+  # If constructor is a Hash, a new mash will be created based on the keys of the hash and
+  # no default value will be set.
   def initialize(constructor = {})
     if constructor.is_a?(Hash)
       super()
@@ -65,11 +62,9 @@ class Mash < Hash
     end
   end
 
-  # @param key<Object> The default value for the mash. Defaults to nil.
-  #
-  # @details [Alternatives]
-  #   If key is a Symbol and it is a key in the mash, then the default value will
-  #   be set to the value matching the key.
+  # @param key [Object] The default value for the mash.
+  # If key is a Symbol and it is a key in the mash, then the default value will be set to
+  # the value matching the key.
   def default(key = nil)
     if key.is_a?(Symbol) && include?(key = key.to_s)
       self[key]
@@ -81,9 +76,8 @@ class Mash < Hash
   alias_method :regular_writer, :[]= unless method_defined?(:regular_writer)
   alias_method :regular_update, :update unless method_defined?(:regular_update)
 
-  # @param key<Object> The key to set.
-  # @param value<Object>
-  #   The value to set the key to.
+  # @param key [Object] The key to set.
+  # @param value [Object] The value to set the key to.
   #
   # @see Mash#convert_key
   # @see Mash#convert_value
@@ -91,7 +85,7 @@ class Mash < Hash
     regular_writer(convert_key(key), convert_value(value))
   end
 
-  # @param other_hash<Hash>
+  # @param other_hash [Hash]
   #   A hash to update values in the mash with. The keys and the values will be
   #   converted to Mash format.
   #
@@ -103,7 +97,7 @@ class Mash < Hash
 
   alias_method :merge!, :update
 
-  # @param key<Object> The key to check for. This will be run through convert_key.
+  # @param key [Object] The key to check for. This will be run through convert_key.
   #
   # @return [Boolean] True if the key exists in the mash.
   def key?(key)
@@ -115,36 +109,34 @@ class Mash < Hash
   alias_method :has_key?, :key?
   alias_method :member?, :key?
 
-  # @param key<Object> The key to fetch. This will be run through convert_key.
-  # @param *extras<Array> Default value.
+  # @param key [Object] The key to fetch. This will be run through convert_key.
+  # @param extras [Array] Default value.
   #
   # @return [Object] The value at key or the default value.
   def fetch(key, *extras)
     super(convert_key(key), *extras)
   end
 
-  # @param *indices<Array>
-  #   The keys to retrieve values for. These will be run through +convert_key+.
+  # @param indices [Array] The keys to retrieve values for. These will be run through +convert_key+.
   #
   # @return [Array] The values at each of the provided keys
   def values_at(*indices)
     indices.collect { |key| self[convert_key(key)] }
   end
 
-  # @param hash<Hash> The hash to merge with the mash.
+  # @param hash [Hash] The hash to merge with the mash.
   #
   # @return [Mash] A new mash with the hash values merged in.
   def merge(hash)
     dup.update(hash)
   end
 
-  # @param key<Object>
-  #   The key to delete from the mash.\
+  # @param key [Object] The key to delete from the mash.
   def delete(key)
     super(convert_key(key))
   end
 
-  # @param *rejected<Array[(String, Symbol)] The mash keys to exclude.
+  # @param keys [Array<String, Symbol>] The mash keys to exclude.
   #
   # @return [Mash] A new mash without the selected keys.
   #
@@ -172,8 +164,8 @@ class Mash < Hash
     Hash.new(default).merge(self)
   end
 
-  # @return [Mash] Convert a Hash into a Mash
-  # The input Hash's default value is maintained
+  # Convert a Hash into a Mash. The input Hash's default value is maintained
+  # @return [Mash]
   def self.from_hash(hash)
     mash = Mash.new(hash)
     mash.default = hash.default
@@ -182,18 +174,15 @@ class Mash < Hash
 
   protected
 
-  # @param key<Object> The key to convert.
-  #
-  # @param [Object]
-  #   The converted key. If the key was a symbol, it will be converted to a
-  #   string.
+  # @param key [Object] The key to convert.
+  # @return [Object] The converted key. If the key was a symbol, it will be converted to a string.
   #
   # @api private
   def convert_key(key)
     key.kind_of?(Symbol) ? key.to_s : key
   end
 
-  # @param value<Object> The value to convert.
+  # @param value [Object] The value to convert.
   #
   # @return [Object]
   #   The converted value. A Hash or an Array of hashes, will be converted to
diff --git a/lib/ohai/mixin/ec2_metadata.rb b/lib/ohai/mixin/ec2_metadata.rb
index 2ed8c461..5dce5a11 100644
--- a/lib/ohai/mixin/ec2_metadata.rb
+++ b/lib/ohai/mixin/ec2_metadata.rb
@@ -72,6 +72,9 @@ module Ohai
         end
       end
 
+      # a net/http client with a timeout of 10s and a keepalive of 10s
+      #
+      # @return [Net::HTTP]
       def http_client
         @conn ||= Net::HTTP.start(EC2_METADATA_ADDR).tap do |h|
           h.read_timeout = 10
@@ -81,11 +84,10 @@ module Ohai
 
       # Get metadata for a given path and API version
       #
-      # @details
-      #   Typically, a 200 response is expected for valid metadata.
-      #   On certain instance types, traversing the provided metadata path
-      #   produces a 404 for some unknown reason. In that event, return
-      #   `nil` and continue the run instead of failing it.
+      # Typically, a 200 response is expected for valid metadata.
+      # On certain instance types, traversing the provided metadata path
+      # produces a 404 for some unknown reason. In that event, return
+      # `nil` and continue the run instead of failing it.
       def metadata_get(id, api_version)
         path = "/#{api_version}/meta-data/#{id}"
         logger.trace("Mixin EC2: Fetching http://#{EC2_METADATA_ADDR}#{path}")
diff --git a/lib/ohai/mixin/gce_metadata.rb b/lib/ohai/mixin/gce_metadata.rb
index 7457e735..a3c20d92 100644
--- a/lib/ohai/mixin/gce_metadata.rb
+++ b/lib/ohai/mixin/gce_metadata.rb
@@ -50,6 +50,9 @@ module Ohai
         end
       end
 
+      # @param [String] data that might be JSON
+      #
+      # @return [Boolean] is the data JSON or not?
       def json?(data)
         data = StringIO.new(data)
         parser = FFI_Yajl::Parser.new
@@ -61,6 +64,9 @@ module Ohai
         end
       end
 
+      # @param data [String]
+      #
+      # @return [Boolean] is there a trailing /?
       def has_trailing_slash?(data)
         !! ( data =~ %r{/$} )
       end
diff --git a/lib/ohai/mixin/http_helper.rb b/lib/ohai/mixin/http_helper.rb
index 290bbc0c..28a99b79 100644
--- a/lib/ohai/mixin/http_helper.rb
+++ b/lib/ohai/mixin/http_helper.rb
@@ -20,6 +20,13 @@ module Ohai
   module Mixin
     module HttpHelper
 
+      # see if we can socket connect to an address/port
+      #
+      # @param addr [String] the address to connect to
+      # @param port [Integer] the port to connect to
+      # @param timeout [Integer] the seconds before timing out
+      #
+      # @return [Boolean] can we connect?
       def can_socket_connect?(addr, port, timeout = 2)
         t = Socket.new(Socket::Constants::AF_INET, Socket::Constants::SOCK_STREAM, 0)
         begin
diff --git a/lib/ohai/mixin/os.rb b/lib/ohai/mixin/os.rb
index b8222596..1af9e2e1 100644
--- a/lib/ohai/mixin/os.rb
+++ b/lib/ohai/mixin/os.rb
@@ -23,6 +23,9 @@ module Ohai
   module Mixin
     module OS
 
+      # Using ruby configuration determine the OS we're running on
+      #
+      # @return [String] the OS
       def collect_os
         case ::RbConfig::CONFIG["host_os"]
         when /aix(.+)$/
diff --git a/lib/ohai/mixin/scaleway_metadata.rb b/lib/ohai/mixin/scaleway_metadata.rb
index e905f429..a547f493 100644
--- a/lib/ohai/mixin/scaleway_metadata.rb
+++ b/lib/ohai/mixin/scaleway_metadata.rb
@@ -23,10 +23,14 @@ module Ohai
       SCALEWAY_METADATA_ADDR = "169.254.42.42" unless defined?(SCALEWAY_METADATA_ADDR)
       SCALEWAY_METADATA_URL = "/conf?format=json" unless defined?(SCALEWAY_METADATA_URL)
 
+      # @return [Net::HTTP] net/http object without timeout set to 6
       def http_client
         Net::HTTP.start(SCALEWAY_METADATA_ADDR).tap { |h| h.read_timeout = 6 }
       end
 
+      # fetch scaleway metadata and parse the resulting JSON
+      #
+      # @return [Hash]
       def fetch_metadata
         uri = "#{SCALEWAY_METADATA_URL}"
         response = http_client.get(uri)
diff --git a/lib/ohai/mixin/seconds_to_human.rb b/lib/ohai/mixin/seconds_to_human.rb
index 6d888970..aa7bb1e7 100644
--- a/lib/ohai/mixin/seconds_to_human.rb
+++ b/lib/ohai/mixin/seconds_to_human.rb
@@ -19,6 +19,11 @@
 module Ohai
   module Mixin
     module SecondsToHuman
+      # given the number of seconds return a day/hours/minutes/seconds human form
+      #
+      # @param seconds [Integer]
+      #
+      # @return String
       def seconds_to_human(seconds)
         days = seconds.to_i / 86400
         seconds -= 86400 * days
diff --git a/lib/ohai/mixin/softlayer_metadata.rb b/lib/ohai/mixin/softlayer_metadata.rb
index 04d33196..caf2b2e3 100644
--- a/lib/ohai/mixin/softlayer_metadata.rb
+++ b/lib/ohai/mixin/softlayer_metadata.rb
@@ -20,10 +20,13 @@
 require "net/https"
 require "uri"
 
-# http://sldn.softlayer.com/reference/services/SoftLayer_Resource_Metadata
+# https://softlayer.github.io/reference/services/SoftLayer_Resource_Metadata/
 module ::Ohai::Mixin::SoftlayerMetadata
   SOFTLAYER_API_QUERY_URL = "https://api.service.softlayer.com/rest/v3.1/SoftLayer_Resource_Metadata" unless defined?(SOFTLAYER_API_QUERY_URL)
 
+  # fetch metadata items and build out hash of data
+  #
+  # @return [Hash]
   def fetch_metadata
     {
       "public_fqdn"   => fetch_metadata_item("getFullyQualifiedDomainName.txt"),
@@ -39,10 +42,16 @@ module ::Ohai::Mixin::SoftlayerMetadata
   # however Chef-omnibus should set SSL_CERT_FILE to point to a valid file.
   # Manually supply and specify a suitable CA bundle here or
   # set the SSL_CERT_FILE file environment variable to a valid value otherwise.
+  #
+  # @return [String]
   def ca_file_location
     ::Ohai::Config[:ca_file]
   end
 
+  # fetch a specified item from the Softlayer metadata API
+  # @param item [String] the metadata item to fetch
+  #
+  # @return [String] the response body
   def fetch_metadata_item(item)
     full_url = "#{SOFTLAYER_API_QUERY_URL}/#{item}"
     u = URI(full_url)
diff --git a/lib/ohai/mixin/string.rb b/lib/ohai/mixin/string.rb
index a10fab2b..a7333b08 100644
--- a/lib/ohai/mixin/string.rb
+++ b/lib/ohai/mixin/string.rb
@@ -22,6 +22,7 @@ class String
   # underscore will also change ’::’ to ’/’ to convert namespaces to paths.
   # This should implement the same functionality as underscore method in
   # ActiveSupport::CoreExtensions::String::Inflections
+  # @return [String]
   def wmi_underscore
     gsub(/::/, "/").gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').
       gsub(/([a-z\d])([A-Z])/, '\1_\2').tr("-", "_").downcase