More docs. Use ActiveSupport delegate to simplify code in places

lib/middleman/base.rb

@@ -304,14 +304,7 @@ class Middleman::Base
   def self.cache
     @_cache ||= ::Middleman::Cache.new
   end
-  
-  # Cache accessor for instance, simply forwards to class
-  #
-  # @private
-  # @return [Middleman::Cache] The cache
-  def cache
-    self.class.cache
-  end
+  delegate :cache, :to => :"self.class"
   
   # Rack env
   attr :env
@@ -465,22 +458,7 @@ protected
     @res.finish
   end
   
-  # Set helpers at the class level
-  def helpers(*extensions, &block)
-    self.class.helpers(*extensions, &block)
-  end
-  
-  # Set middleware at the class level
-  # @return [void]
-  def use(middleware, *args, &block)
-    self.class.use(middleware, *args, &block)
-  end
-  
-  # Set mapped rack app at the class level
-  # @return [void]
-  def map(map, &block)
-    self.class.map(map, &block)
-  end
+  delegate :helpers, :use, :map, :to => :"self.class"
   
   # Immediately send static file
   #

lib/middleman/core_extensions/builder.rb

@@ -8,6 +8,7 @@ module Middleman::CoreExtensions::Builder
       app.define_hook :after_build
       app.extend ClassMethods
       app.send :include, InstanceMethods
+      app.delegate :build_reroute, :to => :"self.class"
     end
     alias :included :registered
   end
@@ -26,13 +27,6 @@ module Middleman::CoreExtensions::Builder
   
   # Build Instance Methods
   module InstanceMethods
-    # Forward to class method
-    #
-    # @return [Array<Proc>]
-    def build_reroute(&block)
-      self.class.build_reroute(&block)
-    end
-    
     # Run through callbacks and get the new values
     #
     # @param [String] destination The current destination of the built file

lib/middleman/core_extensions/default_helpers.rb

@@ -9,8 +9,12 @@ require 'active_support/inflector'                    # humanize
 
 FileSet.glob_require('../vendor/padrino-helpers-0.10.5/lib/padrino-helpers/**/*.rb', __FILE__)
 
+# Built-in helpers
 module Middleman::CoreExtensions::DefaultHelpers
+  
+  # Extension registered
   class << self
+    # @private
     def registered(app)
       app.helpers ::Padrino::Helpers::OutputHelpers
       app.helpers ::Padrino::Helpers::TagHelpers
@@ -30,19 +34,34 @@ module Middleman::CoreExtensions::DefaultHelpers
     alias :included :registered
   end
   
+  # The helpers
   module Helpers
+    # Output a stylesheet link tag based on the current path
+    #
+    # @param [String] separator How to break up path in parts
+    # @return [String]
     def auto_stylesheet_link_tag(separator="/")
       auto_tag(:css, separator) do |path|
         stylesheet_link_tag path
       end
     end
     
+    # Output a javascript tag based on the current path
+    #
+    # @param [String] separator How to break up path in parts
+    # @return [String]
     def auto_javascript_include_tag(separator="/")
       auto_tag(:js, separator) do |path|
         javascript_include_tag path
       end
     end
 
+    # Output a stylesheet link tag based on the current path
+    #
+    # @param [Symbol] asset_ext The type of asset
+    # @param [String] separator How to break up path in parts
+    # @param [String] asset_dir Where to look for assets
+    # @return [void]
     def auto_tag(asset_ext, separator="/", asset_dir=nil)
       if asset_dir.nil?
         asset_dir = case asset_ext
@@ -61,6 +80,9 @@ module Middleman::CoreExtensions::DefaultHelpers
       yield path if sitemap.exists?(File.join(asset_dir, path))
     end
 
+    # Generate body css classes based on the current path
+    #
+    # @return [String]
     def page_classes
       path = current_path.dup
       path << index_file if path.match(%r{/$})
@@ -73,7 +95,11 @@ module Middleman::CoreExtensions::DefaultHelpers
       classes.join(' ')
     end
     
-    # Padrino's asset handling needs to pass through ours
+    # Get the path of a file of a given type
+    # 
+    # @param [Symbol] kind The type of file
+    # @param [String] source The path to the file
+    # @return [String]
     def asset_path(kind, source)
        return source if source =~ /^http/
        asset_folder  = case kind

lib/middleman/core_extensions/extensions.rb

@@ -31,9 +31,12 @@
 # Using for version parsing
 require "rubygems"
 
+# Namespace extensions module
 module Middleman::CoreExtensions::Extensions
   
+  # Register extension
   class << self
+    # @private
     def included(app)
       # app.set :default_extensions, []
       app.define_hook :after_configuration
@@ -43,18 +46,31 @@ module Middleman::CoreExtensions::Extensions
       
       app.extend ClassMethods
       app.send :include, InstanceMethods
+      app.delegate :configure, :to => :"self.class"
     end
   end
 
+  # Class methods
   module ClassMethods
+    # Add a callback to run in a specific environment
+    #
+    # @param [String, Symbol] env The environment to run in
+    # @return [void]
     def configure(env, &block)
       send("#{env}_config", &block)
     end
     
+    # Alias `extensions` to access registered extensions
+    #
+    # @return [Array<Module]
     def extensions
       @extensions ||= []
     end
     
+    # Register a new extension
+    # 
+    # @param [Array<Module>] new_extensions Extension modules to register
+    # @return [Array<Module]
     def register(*new_extensions)
       @extensions ||= []
       @extensions += new_extensions
@@ -65,12 +81,16 @@ module Middleman::CoreExtensions::Extensions
     end
   end
   
+  # Instance methods
   module InstanceMethods
     # This method is available in the project's `config.rb`.
     # It takes a underscore-separated symbol, finds the appropriate
     # feature module and includes it.
     #
     #     activate :lorem
+    #
+    # @param [Symbol, Module] feature Which extension to activate
+    # @return [void]
     def activate(feature)
       ext = ::Middleman::Extensions.load(feature.to_sym)
       
@@ -83,10 +103,6 @@ module Middleman::CoreExtensions::Extensions
         self.class.register(ext)
       end
     end
-
-    def configure(env, &block)
-      self.class.configure(env, &block)
-    end
     
     # Load features before starting server
     def initialize

lib/middleman/core_extensions/file_watcher.rb

@@ -1,11 +1,17 @@
 require "find"
 
+# API for watching file change events
 module Middleman::CoreExtensions::FileWatcher
+  # Setup extension
   class << self
+    # @private
     def registered(app)
       app.extend ClassMethods
       app.send :include, InstanceMethods
       
+      app.delegate :file_changed, :file_deleted, :to => :"self.class"
+      
+      # Before parsing config, load the data/ directory
       app.before_configuration do
         data_path = File.join(root, data_dir)
         Find.find(data_path) do |path|
@@ -14,6 +20,7 @@ module Middleman::CoreExtensions::FileWatcher
         end if File.exists?(data_path)
       end
       
+      # After config, load everything else
       app.ready do
         Find.find(root) do |path|
           next if File.directory?(path)
@@ -24,13 +31,22 @@ module Middleman::CoreExtensions::FileWatcher
     alias :included :registered
   end
   
+  # Class methods
   module ClassMethods
+    # Add callback to be run on file change
+    #
+    # @param [nil,Regexp] matcher A Regexp to match the change path against
+    # @return [Array<Proc>]
     def file_changed(matcher=nil, &block)
       @_file_changed ||= []
       @_file_changed << [block, matcher] if block_given?
       @_file_changed
     end
     
+    # Add callback to be run on file deletion
+    #
+    # @param [nil,Regexp] matcher A Regexp to match the deleted path against
+    # @return [Array<Proc>]
     def file_deleted(matcher=nil, &block)
       @_file_deleted ||= []
       @_file_deleted << [block, matcher] if block_given?
@@ -38,11 +54,12 @@ module Middleman::CoreExtensions::FileWatcher
     end
   end
   
+  # Instance methods
   module InstanceMethods
-    def file_changed(*args, &block)
-      self.class.file_changed(*args, &block)
-    end
-    
+    # Notify callbacks that a file changed
+    #
+    # @param [String] path The file that changed
+    # @return [void]
     def file_did_change(path)
       file_changed.each do |callback, matcher|
         next if path.match(%r{^#{build_dir}/})
@@ -50,11 +67,11 @@ module Middleman::CoreExtensions::FileWatcher
         instance_exec(path, &callback)
       end
     end
-    
-    def file_deleted(*args)
-      self.class.file_deleted(*args)
-    end
 
+    # Notify callbacks that a file was deleted
+    #
+    # @param [String] path The file that was deleted
+    # @return [void]
     def file_did_delete(path)
       file_deleted.each do |callback, matcher|
         next if path.match(%r{^#{build_dir}/})

lib/middleman/core_extensions/front_matter.rb

@@ -7,6 +7,7 @@ module Middleman::CoreExtensions::FrontMatter
       app.set :frontmatter_extensions, %w(.htm .html .php)
       app.extend ClassMethods
       app.send :include, InstanceMethods
+      app.delegate :frontmatter_changed, :to => :"self.class"
     end
     alias :included :registered
   end
@@ -55,10 +56,6 @@ module Middleman::CoreExtensions::FrontMatter
         { :options => data }
       end
     end
-    
-    def frontmatter_changed(*args, &block)
-      self.class.frontmatter_changed(*args, &block)
-    end
 
     def frontmatter_did_change(path)
       frontmatter_changed.each do |callback, matcher|