From f8a8aed228561fd3b746e9973c04fbe1c6671bd8 Mon Sep 17 00:00:00 2001 From: Tim Smith Date: Sun, 23 Sep 2018 13:46:02 -0700 Subject: Add more yard comments Signed-off-by: Tim Smith --- lib/ohai/application.rb | 19 +++++++++++++++++++ lib/ohai/exception.rb | 1 + lib/ohai/hints.rb | 5 +++++ lib/ohai/log.rb | 2 ++ lib/ohai/system.rb | 14 ++++++++++++-- 5 files changed, 39 insertions(+), 2 deletions(-) diff --git a/lib/ohai/application.rb b/lib/ohai/application.rb index 2944dc16..c7d335b0 100644 --- a/lib/ohai/application.rb +++ b/lib/ohai/application.rb @@ -22,6 +22,10 @@ require "ohai/log" require "mixlib/cli" require "benchmark" +# The Application class is what is called by the Ohai CLI binary. It handles: +# - CLI options and attribute arguments +# - Collecting data via the Ohai::System class +# - Printing the results returned via the Ohai::System class class Ohai::Application include Mixlib::CLI @@ -69,6 +73,9 @@ class Ohai::Application proc: lambda { |v| puts "Ohai: #{::Ohai::VERSION}" }, exit: 0 + # the method called by the Ohai binary to actually run the whole application + # + # @return void def run elapsed = Benchmark.measure do configure_ohai @@ -77,6 +84,9 @@ class Ohai::Application Ohai::Log.debug("Ohai took #{elapsed.total} total seconds to run.") end + # parses the CLI options, loads the config file if present, and initializes logging + # + # @return void def configure_ohai @attributes = parse_options @attributes = nil if @attributes.empty? @@ -86,6 +96,10 @@ class Ohai::Application Ohai::Log.init(Ohai.config[:log_location]) end + # Passes config and attributes arguments to Ohai::System then prints the results. + # Called by the run method after config / logging have been initialized + # + # @return void def run_application # Always switch to a readable directory. Keeps subsequent Dir.chdir() {} # from failing due to permissions when launched as a less privileged user. @@ -107,12 +121,17 @@ class Ohai::Application class << self # Log a fatal error message to both STDERR and the Logger, exit the application + # @param msg [String] the message to log + # @param err [Integer] the exit code def fatal!(msg, err = -1) STDERR.puts("FATAL: #{msg}") Ohai::Log.fatal(msg) Process.exit err end + # Log a debug message to the Logger and then exit the application + # @param msg [String] the message to log + # @param err [Integer] the exit code def exit!(msg, err = -1) Ohai::Log.debug(msg) Process.exit err diff --git a/lib/ohai/exception.rb b/lib/ohai/exception.rb index 0cae0995..65258d89 100644 --- a/lib/ohai/exception.rb +++ b/lib/ohai/exception.rb @@ -17,6 +17,7 @@ # module Ohai + # Ohai specific exceptions module Exceptions class Exec < RuntimeError; end class Error < StandardError; end diff --git a/lib/ohai/hints.rb b/lib/ohai/hints.rb index fd568aa6..ffa02a43 100644 --- a/lib/ohai/hints.rb +++ b/lib/ohai/hints.rb @@ -20,6 +20,11 @@ require "ffi_yajl" module Ohai + # Ohai hints are json files on disk that give ohai a hint to things that are often + # difficult to discover like certain clouds. Previously they were used for just about + # every cloud, but we've since discoverd better ways to auto-detect these clouds. + # They are generally dropped off by the knife plugins for those clouds during bootstrap, + # but may also be manually dropped off and consumed by 3rd party plugins. module Hints # clear out any known hints in the @hints variable def self.refresh_hints diff --git a/lib/ohai/log.rb b/lib/ohai/log.rb index 91a8c78e..6cf0ec2e 100644 --- a/lib/ohai/log.rb +++ b/lib/ohai/log.rb @@ -19,6 +19,8 @@ require "mixlib/log" module Ohai + # the Ohai Logger which is just Mixlib::Log defaulting to STDERR and :info level + # unless otherwise configured via CLI or config class Log extend Mixlib::Log diff --git a/lib/ohai/system.rb b/lib/ohai/system.rb index 74e80d54..b6056d37 100644 --- a/lib/ohai/system.rb +++ b/lib/ohai/system.rb @@ -32,6 +32,7 @@ require "ohai/config" require "ffi_yajl" module Ohai + # The class used by Ohai::Application and Chef to actually collect data class System include Ohai::Mixin::ConstantHelper @@ -78,9 +79,10 @@ module Ohai @data[key] end - # resets the system and loads then runs the plugins + # Resets the system and loads then runs the plugins. This is the primary method called + # to run the system. # - # @param [Array] attribute_filter + # @param [Array] attribute_filter the attributes to run. All will be run if not specified # @return [void] def all_plugins(attribute_filter = nil) # Reset the system when all_plugins is called since this function @@ -92,10 +94,18 @@ module Ohai run_plugins(true, attribute_filter) end + # load all plugins by calling Ohai::Loader.load_all + # @see Ohai::Loader.load_all def load_plugins @loader.load_all end + # run all plugins or those that match the attribute filter is provided + # + # @param safe [Boolean] + # @param [Array] attribute_filter the attributes to run. All will be run if not specified + # + # @return [Mash] def run_plugins(safe = false, attribute_filter = nil) begin @provides_map.all_plugins(attribute_filter).each do |plugin| -- cgit v1.2.1