Add more yard commentsyard++

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

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<String>] attribute_filter
+    # @param [Array<String>] 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<String>] 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|