diff options
author | Tim Smith <tsmith@chef.io> | 2018-05-18 06:32:54 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-05-18 06:32:54 -0700 |
commit | a11322f5774f9dd06f051250ca9d288aa9ac4c31 (patch) | |
tree | 977161d8bfab18a72a5ed9b15a1042d47b282cfe | |
parent | ebc86a036460d1e2f95b6a9e78153914a8be6ab1 (diff) | |
parent | 921ac5d2327f9f982a2677b9c9767f226b4ec0a9 (diff) | |
download | ohai-a11322f5774f9dd06f051250ca9d288aa9ac4c31.tar.gz |
Merge pull request #1187 from chef/comments
Fix yard parsing issues & add more commments
-rw-r--r-- | lib/ohai/common/dmi.rb | 11 | ||||
-rw-r--r-- | lib/ohai/dsl/plugin.rb | 6 | ||||
-rw-r--r-- | lib/ohai/dsl/plugin/versionvii.rb | 33 | ||||
-rw-r--r-- | lib/ohai/hints.rb | 8 | ||||
-rw-r--r-- | lib/ohai/mash.rb | 53 | ||||
-rw-r--r-- | lib/ohai/mixin/ec2_metadata.rb | 12 | ||||
-rw-r--r-- | lib/ohai/mixin/gce_metadata.rb | 6 | ||||
-rw-r--r-- | lib/ohai/mixin/http_helper.rb | 7 | ||||
-rw-r--r-- | lib/ohai/mixin/os.rb | 3 | ||||
-rw-r--r-- | lib/ohai/mixin/scaleway_metadata.rb | 4 | ||||
-rw-r--r-- | lib/ohai/mixin/seconds_to_human.rb | 5 | ||||
-rw-r--r-- | lib/ohai/mixin/softlayer_metadata.rb | 11 | ||||
-rw-r--r-- | lib/ohai/mixin/string.rb | 1 |
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 |