nucleon 0.2.2 → 0.2.3

data/lib/core/util/logger.rb

@@ -1,45 +1,132 @@
-
 module Nucleon
 module Util
+#
+# == Logger
+#
+# The Nucleon::Util::Logger class defines a logging interface that wraps the Log4r
+# gem interface to provide all Nucleon classes with logging capabilities.
+#
+# Logging methods exposed:
+#
+# 1. *error*  Display all serious errors
+# 2. *warn*  Warnings that do not trigger an error
+# 3. *info*  Concise runtime information
+# 4. *debug*  Potentially verbose debug information
+#
+# *Note*:  This is the first Nucleon library loaded so it can *NOT* depend on
+# any other library or core object.
+#
+# See also:
+# - Nucleon::Core (base logging capable object)
+#
 class Logger
-  
-  #-----------------------------------------------------------------------------
+
+  #*****************************************************************************
   # Properties
-  
-  @@level   = nil
+
+  #
+  # Global log level
+  #
+  # Can be:
+  # - *:debug*
+  # - *:info*
+  # - *:warn*
+  # - *:error*
+  #
+  @@level = nil
+
+  #
+  # Global collection of instantiated loggers
+  #
   @@loggers = {}
-  
-  #---
-  
+
+  # Check current global log level
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [Symbol]  Global log level; *:debug*, *:info*, *:warn*, *:error*
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::level=
+  #
   def self.level
-    @@level  
+    @@level
   end
-  
+
+  # Set current global log level
+  #
+  # * *Parameters*
+  #   - [Symbol] *level*  Global log level; *:debug*, *:info*, *:warn*, *:error*
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::level
+  # - ::set_level
+  #
   def self.level=level
     @@level = set_level(level)
   end
-  
-  #---
-  
+
+  # Return a reference to all globally instantiated loggers
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [Hash<Symbol|Log4r>]  Collection of globally accessible loggers
+  #
+  # * *Errors*
+  #
   def self.loggers
     @@loggers
   end
-  
-  #---
-  
+
+  # Define a list of Log4r levels
+  #
+  # Due to how Log4r is built this can only happen at the very beginning of our
+  # execution run before any loggers are instantiated.
+  #
+  # This should never be called directly outside of this class.
+  #
+  # * *Parameters*
+  #   - [Symbol, String, Array<Symbol, String>] *levels*  Available log levels
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
   def self.set_levels(*levels)
-    levels = levels.flatten.collect do |level| 
+    levels = levels.flatten.collect do |level|
       level.to_s.upcase
     end
     Log4r::Configurator.custom_levels(*levels)
   end
-  
-  #---
-  
+
+  # Set the logging level for either all instantiated loggers or a specified logger.
+  #
+  # * *Parameters*
+  #   - [Symbol, String] *level*  Global log level; *:debug*, *:info*, *:warn*, *:error*
+  #   - [Log4r] *logger*  Log4r instance to set log level or all if none provided
+  #
+  # * *Returns*
+  #   - [Symbol]  Return the current global log level
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::level=
+  #
   def self.set_level(level, logger = nil)
     level_sym = level.to_s.downcase.to_sym
     level_id  = level.to_s.upcase
-    
+
     if logger.nil?
       loggers.each do |name, registered_logger|
         @@loggers[name].level = Log4r.const_get(level_id)
@@ -51,37 +138,78 @@ class Logger
     end
     level_sym
   end
-  
-  #---
-  
+
+  # Add a instantiated logger to the global logger registry.
+  #
+  # TODO: Is there a better way to handle the outputter for more flexibility?
+  #
+  # * *Parameters*
+  #   - [Symbol, String] *name*  Logger name
+  #   - [Log4r] *logger*  Log4r instance to register
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::set_level
+  #
   def self.add_logger(name, logger)
     logger.outputters = Log4r::StdoutOutputter.new('console')
-    
+
     level = Logger.level.nil? ? 'off' : Logger.level
-    set_level(level, logger)  
-        
-    @@loggers[name] = logger
+    set_level(level, logger)
+
+    @@loggers[name.to_sym] = logger
   end
-  
+
+  #
   # Initialize log levels
-  
-  set_levels :debug, :info, :warn, :error, :hook
-    
+  #
+  # *IMPORTANT*  Log levels must be registered before Log4r instances are created
+  #
+  # TODO: This process does not work when using as a library through another
+  # executable that already loads Log4r.
+  #
+  set_levels :debug, :info, :warn, :error
+
+  #
+  # Set starting log level if defined in "NUCLEON_LOG" environment variable
+  #
   if ENV['NUCLEON_LOG']
     Logger.level = ENV['NUCLEON_LOG']
   end
-  
-  #-----------------------------------------------------------------------------
+
+  #*****************************************************************************
   # Constructor
-  
+
+  # Initialize a new logging object
+  #
+  # TODO: Figure out some way to make the logger system pluggable?
+  #
+  # * *Parameters*
+  #   - [Hash] *options*  Logger options
+  #     - [String] *:resource*  Logger resource identifier (also serves as prefix)
+  #     - [nil, Log4r] *:logger*  Log4r logger of nil if new one created
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - #logger=
+  # - Nucleon::Config::ensure
+  #
   def initialize(options = {})
     if options.is_a?(String)
       options = { :logger => options }
     end
     config = Config.ensure(options)
-    
+
     @resource = config.get(:resource, '')
-    
+
     if config.get(:logger, false)
       self.logger = config[:logger]
     else
@@ -89,19 +217,42 @@ class Logger
     end
   end
 
-  #---
-  
+  # Return a string reference that identifies this logger
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [String]  Identification string
+  #
+  # * *Errors*
+  #
   def inspect
     "#<#{self.class}: #{@resource}>"
   end
-   
-  #-----------------------------------------------------------------------------
+
+  #*****************************************************************************
   # Accessors / Modifiers
-  
+
+  #
+  # [String]  Logger resource name
+  #
+  # This is the string identifier and logger prefix used when logging.
+  #
   attr_reader :resource
-  
-  #---
-  
+
+  # Set current logger object
+  #
+  # * *Parameters*
+  #   - [String, Log4r] *logger*  Log4r object or string resource name
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::add_logger
+  #
   def logger=logger
     if logger.is_a?(String)
       @resource = logger
@@ -109,49 +260,87 @@ class Logger
     else
       @logger = logger
     end
-    self.class.add_logger(@resource, @logger) unless self.class.loggers.has_key?(@resource)  
+    self.class.add_logger(@resource, @logger) unless self.class.loggers.has_key?(@resource)
   end
-  
-  #-----------------------------------------------------------------------------
+
+  #*****************************************************************************
   # Log statements
-  
+
+  # Log a debug message
+  #
+  # * *Parameters*
+  #   - [String] *message*  Debug related message
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - Nucleon::Util::Console::quiet
+  #
   def debug(message)
     unless Util::Console.quiet
       @logger.debug(message)
     end
   end
-  
-  #---
-  
+
+  # Log an info message
+  #
+  # * *Parameters*
+  #   - [String] *message*  Concise informational message
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - Nucleon::Util::Console::quiet
+  #
   def info(message)
     unless Util::Console.quiet
       @logger.info(message)
     end
   end
-  
-  #---
-  
+
+  # Log a warning message (non error)
+  #
+  # * *Parameters*
+  #   - [String] *message*  Warning message
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - Nucleon::Util::Console::quiet
+  #
   def warn(message)
     unless Util::Console.quiet
       @logger.warn(message)
     end
   end
-  
-  #---
-  
+
+  # Log an error message
+  #
+  # * *Parameters*
+  #   - [String] *message*  Error message
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - Nucleon::Util::Console::quiet
+  #
   def error(message)
     unless Util::Console.quiet
       @logger.error(message)
     end
   end
-  
-  #---
-  
-  def hook(message)
-    unless Util::Console.quiet
-      @logger.hook(message)
-    end
-  end         
 end
 end
 end

data/lib/nucleon.rb

@@ -1,17 +1,15 @@
-
-#*******************************************************************************
-# Nucleon
 #
-# Framework that provides a simple foundation for building distributively 
-# configured, extremely pluggable and extendable, and easily parallel 
-# applications.
+# == Nucleon
+#
+# Framework that provides a simple foundation for building distributed,
+# pluggable, and integrated applications.
 #
 # Author::    Adrian Webb (mailto:adrian.webb@coralnexus.com)
-# License::   GPLv3
+# License::   Apache License, version 2
 
 require File.join(File.dirname(__FILE__), "nucleon_base.rb")
 
-#-------------------------------------------------------------------------------
+#*******************************************************************************
 # Core initialization
 
 Nucleon.reload(true)

data/lib/nucleon_base.rb

@@ -1,18 +1,36 @@
-#*******************************************************************************
-# Nucleon
 #
-# Framework that provides a simple foundation for building distributively 
-# configured, extremely pluggable and extendable, and easily parallel 
-# applications.
+# == Nucleon
+#
+# Framework that provides a simple foundation for building distributed,
+# pluggable, and integrated applications.
 #
 # Author::    Adrian Webb (mailto:adrian.webb@coralnexus.com)
-# License::   GPLv3
+# License::   Apache License, version 2
+
 
-#-------------------------------------------------------------------------------
+#*******************************************************************************
 # Global namespace
 
+# Kernel module additions
+#
+# These methods, all of which are prefixed with "nucleon_" are available in any
+# class or module within the Nucleon framework or derivatives.
+#
 module Kernel
-    
+
+  # Locate an application command or return nil otherwise.
+  #
+  # This is used to check for applications, such as Git, so that we may
+  # conditionally install packages based upon applications installed.
+  #
+  # * *Parameters*
+  #   - [String, Symbol] *command*  Command name to locale on system
+  #
+  # * *Returns*
+  #   - [nil, String]  File path to executable or nil if not found
+  #
+  # * *Errors*
+  #
   def nucleon_locate(command)
     command = command.to_s
     exts    = ENV['PATHEXT'] ? ENV['PATHEXT'].split(';') : ['']
@@ -24,70 +42,208 @@ module Kernel
     end
     return nil
   end
-    
-  #---
-  
+
+  # Require resource files into Nucleon execution flow.
+  #
+  # This method auto-requires resources in the following order:
+  #
+  # 1. *{name}.rb*
+  # 2. *{base_dir/name}/**/*.rb
+  #
+  # If resources within the directory depend on each other those requires should
+  # be present in the resource files doing the requiring so we don't get load
+  # order conflicts.
+  #
+  # * *Parameters*
+  #   - [String, Symbol] *base_dir*  Command name to locale on system
+  #   - [String, Symbol] *name*  Command name to locale on system
+  #
+  # * *Returns*
+  #   - [Void]  This method does not have a return value
+  #
+  # * *Errors*
+  #
   def nucleon_require(base_dir, name)
-    name = name.to_s
+    base_dir       = base_dir.to_s
+    name           = name.to_s
     top_level_file = File.join(base_dir, "#{name}.rb")
-    
-    require top_level_file if File.exists?(top_level_file) 
-     
+
+    require top_level_file if File.exists?(top_level_file)
+
     directory = File.join(base_dir, name)
-      
+
     if File.directory?(directory)
       Dir.glob(File.join(directory, '**', '*.rb')).each do |sub_file|
         require sub_file
       end
-    end  
+    end
   end
 end
 
-#-------------------------------------------------------------------------------
-# Load paths 
+#*******************************************************************************
+# Load paths
 
-lib_dir          = File.dirname(__FILE__)
-core_dir         = File.join(lib_dir, 'core')
-mixin_dir        = File.join(core_dir, 'mixin')
+#
+# The following variables refer to Nucleon file load paths loaded during
+# initialization.
+#
+
+#
+# Base library path
+#
+lib_dir = File.dirname(__FILE__)
+#
+# Core class load path
+#
+core_dir = File.join(lib_dir, 'core')
+#
+# Base mixin load path
+#
+mixin_dir = File.join(core_dir, 'mixin')
+#
+# Configuration mixin load path
+#
 mixin_config_dir = File.join(mixin_dir, 'config')
+#
+# Action mixin load path
+#
 mixin_action_dir = File.join(mixin_dir, 'action')
-macro_dir        = File.join(mixin_dir, 'macro')
-util_dir         = File.join(core_dir, 'util')
-mod_dir          = File.join(core_dir, 'mod')
-plugin_dir       = File.join(core_dir, 'plugin')
+#
+# Macro mixin load path
+#
+macro_dir = File.join(mixin_dir, 'macro')
+#
+# Utilities load path
+#
+util_dir = File.join(core_dir, 'util')
+#
+# Mod load path (monkey patches)
+#
+mod_dir = File.join(core_dir, 'mod')
+#
+# Base plugin load path
+#
+plugin_dir = File.join(core_dir, 'plugin')
 
-#-------------------------------------------------------------------------------
+#*******************************************************************************
 # Environment checks and debugging
 
+# Nucleon top level module
+#
+# Any methods contained in this file are purely for enabling early checks or
+# operations needed for loading Nucleon effectively?
+#
+# Most methods to the Nucleon module should be loaded via the Nucleon::Facade.
+#
 module Nucleon
-  
+
+  # Get currently loaded versioin of Nucleon
+  #
+  # This method loads from the VERSION file in the top level directory.  This file
+  # gets automatically updated as we build and release new versions.
+  #
+  # See the Rakefile and the Coral Toolbox project at:
+  #
+  # http://github.com/coralnexus/coral-toolbox
+  #
+  # *Note*: This process might change in the near future.
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [String]  Currently loaded version of Nucleon framework
+  #
+  # * *Errors*
+  #
   def self.VERSION
-    File.read(File.join(File.dirname(__FILE__), '..', 'VERSION'))  
+    File.read(File.join(File.dirname(__FILE__), '..', 'VERSION'))
   end
-  
-  #-----------------------------------------------------------------------------
-  
+
+  #*****************************************************************************
+
+  #
+  # Global flag that indicate whether or not dumping with dbg() is active
+  #
+  # Think of this as a global on/off switch in case dbg() statements are
+  # accidentally left in code.
+  #
   @@dump_enabled = false
-  
+
+  # Enable or disable variable dumping through dbg()
+  #
+  # * *Parameters*
+  #   - [Boolean] *dump*  Whether or not to enable dumping through dbg()
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::dump_enabled
+  #
   def self.dump_enabled=dump
     @@dump_enabled = dump
   end
-  
+
+  # Check whether dumping is enabled or disabled through dbg()
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [Boolean]  Whether or not to enable dumping through dbg()
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::dump_enabled=
+  #
   def self.dump_enabled
     @@dump_enabled
   end
- 
-  #-----------------------------------------------------------------------------
-  
+
+  #*****************************************************************************
+
+  # Check if debugging is enabled
+  #
+  # This uses the environment variable *"NUCLEON_DEBUG"*
+  #
+  #   ENV["NUCLEON_DEBUG"]
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [Boolean]  Whether or not debugging is enabled
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::debug_break
+  #
   def self.debugging?
-    ENV["NUCLEON_DEBUG"] ? true : false  
+    ENV["NUCLEON_DEBUG"] ? true : false
   end
-  
-  #---
-  
+
+  # Set a debug break poing at the line of invocation if debugging is enabled.
+  #
+  # Nucleon uses Pry to perform stepwise debugging through the code.
+  #
+  # Note: This is not used very often so it may be buggy in areas.
+  #
+  # * *Parameters*
+  #   - [Boolean] *condition*  Boolean test to check if the debugging breakpoint should be active
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::debugging?
+  #
   def self.debug_break(condition = true)
     if debugging?
-#-------------------------------------------------------------------------------
+#*******************************************************************************
 # Nucleon Pry powered development console
 #
 # Usage:
@@ -97,15 +253,15 @@ module Nucleon
 #
 #   :> [ sudo ] NUCLEON_DEBUG=1 nucleon <args>...
 #
-# * Call the debug_break method anywhere in the code to start a debugging 
+# * Call the debug_break method anywhere in the code to start a debugging
 #   session.
 #
 #   :> Nucleon.debug_break   or    :> Nucleon.debug_break <test?>
 #
-# * Since the debugging tools don't work in parallel, parallel operations are 
+# * Since the debugging tools don't work in parallel, parallel operations are
 #   serialized when NUCLEON_DEBUG environment variable is found.
 #
-#-------------------------------------------------------------------------------
+#*******************************************************************************
 # General information
 #
 # For more information on Pry: http://pryrepl.org
@@ -117,14 +273,14 @@ module Nucleon
 # For available commands and help information: [ help ]
 # For command specific help:                   [ <command> --help ]
 #
-#-------------------------------------------------------------------------------
+#*******************************************************************************
 # General commands:
 #
 # :> cd <Class>                Change to inspect class (class constant)
 # :> show-method <method>      Show source for class method
 # :> .<CLI command> <args>...  Execute a CLI command (always starts with dot)
 #
-#-------------------------------------------------------------------------------
+#*******************************************************************************
 # Breakpoints
 #
 # :> breakpoints                             List all defined breakpoints
@@ -143,7 +299,7 @@ module Nucleon
 #
 # :> break --show <breakpoint>               Show details about breakpoint.
 #
-#-------------------------------------------------------------------------------
+#*******************************************************************************
 # Stack inspection / traversal
 #
 # :> show-stack      Show all accessible frames in the call stack.
@@ -151,7 +307,7 @@ module Nucleon
 # :> up              Move up one frame in the call stack.
 # :> down            Move down one frame in the call stack.
 #
-#-------------------------------------------------------------------------------
+#*******************************************************************************
 # Debugging execution flow:
 #
 # :> s = [ step | step <times> ]  Step execution into the next line or method.
@@ -160,28 +316,78 @@ module Nucleon
 # :> c = [ continue ]             Continue program execution (end Pry session).
 #
       binding.pry if condition
-    end  
+    end
   end
-  
-  #-----------------------------------------------------------------------------
-  
+
+  #*****************************************************************************
+
+  # Check if parallel execution is enabled
+  #
+  # This uses the environment variable *"NUCLEON_NO_PARALLEL"*.  Parallelism is
+  # enabled by default.
+  #
+  #   ENV["NUCLEON_NO_PARALLEL"]
+  #
+  # Due to the complications with parallel debugging, parallel is suspended
+  # when debugging is enabled
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [Boolean]  Whether or not parallel is enabled
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::debugging?
+  #
   def self.parallel?
     debugging? || ENV['NUCLEON_NO_PARALLEL'] ? false : true
   end
-  
-  #---
-  
+
+  #
+  # Global console Mutex lock
+  #
+  # TODO: This may not be needed?
+  #
   @@console_lock = Mutex.new
-  
+
+  # Get the global console Mutex for synchronized console operations.
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [Mutex]  Console Mutex object
+  #
+  # * *Errors*
+  #
   def self.console_lock
     @@console_lock
-  end  
+  end
 end
 
-#-------------------------------------------------------------------------------
+#*******************************************************************************
 
+#
+# We also define a generic debug dump method that is available in any Nucleon
+# derived class or module.
+#
 module Kernel
-  
+
+  # Dump data to the console with optional label.
+  #
+  # This must be defined under the definition of Nucleon::dump_enabled
+  #
+  # * *Parameters*
+  #   - [ANY] *data*  Data to dump to the console
+  #   - [String] *label*  Label to render above data dump
+  #   - [Boolean] *override_enabled*  Whether or not to override override Nucleon::dump_enabled
+  #
+  # * *Returns*
+  #   - [Void]  This method does not have a return value
+  #
+  # * *Errors*
+  #
   def dbg(data, label = '', override_enabled = false)
     # Invocations of this function should NOT be committed to the project
     if Nucleon.dump_enabled || override_enabled
@@ -196,79 +402,126 @@ module Kernel
     end
   end
 end
-  
-#-------------------------------------------------------------------------------
+
+#*******************************************************************************
 # Coral requirements
 
+#
+# Initialize Gem load path
+#
 $:.unshift(lib_dir) unless $:.include?(lib_dir) || $:.include?(File.expand_path(lib_dir))
 
-#---
-
+#
+# Only require debugging packages if debugging is enabled
+#
 if Nucleon.debugging?
   require 'pry'
   require 'pry-stack_explorer'
-  require 'pry-debugger'
+  require 'pry-byebug'
 
   if defined?(PryDebugger)
     Pry.commands.alias_command 'c', 'continue'
     Pry.commands.alias_command 's', 'step'
     Pry.commands.alias_command 'n', 'next'
     Pry.commands.alias_command 'f', 'finish'
-  end 
+  end
 end
 
-#---
-
+#
+# General requirements
+#
 # TODO: Reduce the number of dependencies loaded in this load script (for performance).
 # Decentralize!
 
+#
+# Allows us to work with Gem objects
+#
+# See:
+# - Nucleon::Gems
+#
 require 'rubygems'
-
+#
+# Basic CLI option parsing
+#
 require 'optparse'
+#
+# Internationalization
+#
 require 'i18n'
+#
+# Logging capabilities
+#
 require 'log4r'
 require 'log4r/configurator'
+#
+# Data merging
+#
 require 'deep_merge'
-
+#
+# SHA1 identification
+#
 require 'digest/sha1'
+#
+# Object serialization
+#
 require 'base64'
-
+#
+# YAML parsing / generation
+#
 require 'yaml'
+#
+# JSON parsing / generation
+#
 require 'multi_json'
-
+#
+# Temp directory access
+#
 require 'tmpdir'
+#
+# SSH private / public key access and generation
+#
 require 'sshkey'
-
+#
+# Sub process execution
+#
 require 'childprocess'
+#
+# Basic threading
+#
 require 'thread'
-
+#
+# Celluloid actors
+#
 if Nucleon.parallel?
   require 'celluloid'
-  require 'celluloid/autostart'  
+  require 'celluloid/autostart'
 end
 
-#---
-
+#
+# I18n settings
+#
 # TODO: Make this dynamically settable
-
+#
 I18n.enforce_available_locales = false
 I18n.load_path << File.expand_path(File.join('..', 'locales', 'en.yml'), lib_dir)
 
-#---
-
-# Make sure logger is at the top of our load order priorities
+#
+# Logger
+#
+# *IMPORTANT*  Make sure logger is at the top of our load order priorities
+#
 nucleon_require(util_dir, :logger)
 
-#---
-
+#
 # Object modifications (100% pure monkey patches)
+#
 Dir.glob(File.join(mod_dir, '*.rb')).each do |file|
   require file
 end
 
-#---
-
-# Mixins for classes
+#
+# Class mixins
+#
 Dir.glob(File.join(mixin_dir, '*.rb')).each do |file|
   require file
 end
@@ -282,48 +535,53 @@ Dir.glob(File.join(macro_dir, '*.rb')).each do |file|
   require file
 end
 
-#---
-
+#
+# Nucleon facade
+#
 nucleon_require(core_dir, :facade)
 
+#
+# Nucleon::Facade extends Nucleon
+#
 module Nucleon
   extend Facade
 end
 
-#---
-
-# Include bootstrap classes
+#
+# Bootstrap classes
+#
 nucleon_require(core_dir, :errors)
 nucleon_require(core_dir, :codes)
 nucleon_require(util_dir, :data)
 nucleon_require(core_dir, :config)
-nucleon_require(util_dir, :console) 
-nucleon_require(core_dir, :core) 
-
-#---
+nucleon_require(util_dir, :console)
+nucleon_require(core_dir, :core)
 
-# Include core utilities
-[ :liquid, 
-  :cli, 
-  :disk, 
+#
+# Core utilities
+#
+[ :liquid,
+  :cli,
+  :disk,
   :package,
-  :cache, 
+  :cache,
   :shell,
   :ssh
-].each do |name| 
+].each do |name|
   nucleon_require(util_dir, name)
 end
 
-#---
-
+#
+# Git (if it exists on the system)
+#
 if nucleon_locate('git')
   require 'rugged'
   nucleon_require(util_dir, :git)
 end
 
-#---
-
-# Include plugin system
+#
+# Nucleon plugin system
+#
 nucleon_require(core_dir, :gems)
 nucleon_require(core_dir, :environment)
 nucleon_require(core_dir, :manager)