Add more yard commentscomments

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

9 files changed, 41 insertions, 2 deletions

diff --git a/lib/ohai/hints.rb b/lib/ohai/hints.rb
index 7a32c7d5..a3501ea0 100644
--- a/lib/ohai/hints.rb
+++ b/lib/ohai/hints.rb
@@ -26,7 +26,8 @@ module Ohai
       @hints = {}
     end
 
-    # parse the JSON conents of a hint file
+    # 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
diff --git a/lib/ohai/mixin/ec2_metadata.rb b/lib/ohai/mixin/ec2_metadata.rb
index f01c05d7..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
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