From c7249a63b1d200b578c04213104e5f07adeae135 Mon Sep 17 00:00:00 2001
From: Thomas Reynolds <me@tdreyno.com>
Date: Sat, 31 Dec 2011 14:28:17 -0800
Subject: [PATCH] middleman-more is fully rdoc'd

---
 .../lib/middleman-core/renderers/erb.rb       | 10 +++++
 middleman-more/lib/middleman-more.rb          |  4 +-
 .../middleman-more/core_extensions/compass.rb |  3 +-
 .../core_extensions/sprockets.rb              | 41 +++++++++++++++++--
 .../middleman-more/extensions/cache_buster.rb | 15 +++++++
 .../middleman-more/extensions/minify_css.rb   |  9 ++++
 .../extensions/minify_javascript.rb           | 21 ++++++++++
 .../extensions/relative_assets.rb             | 16 ++++++++
 .../lib/middleman-more/renderers/haml.rb      | 10 ++++-
 .../lib/middleman-more/renderers/liquid.rb    |  9 ++++
 .../lib/middleman-more/renderers/markdown.rb  | 13 ++++++
 .../lib/middleman-more/renderers/sass.rb      | 23 +++++++++++
 .../lib/middleman-more/renderers/slim.rb      |  7 ++++
 13 files changed, 173 insertions(+), 8 deletions(-)

diff --git a/middleman-core/lib/middleman-core/renderers/erb.rb b/middleman-core/lib/middleman-core/renderers/erb.rb
index 7c1bf44c..4290affd 100644
--- a/middleman-core/lib/middleman-core/renderers/erb.rb
+++ b/middleman-core/lib/middleman-core/renderers/erb.rb
@@ -1,16 +1,26 @@
+# ERb renderer
 module Middleman::Renderers::ERb
+  
+  # Setup extension
   class << self
+    
+    # once registered
     def registered(app)
+      # Setup a default ERb engine
       app.set :erb_engine, :erb
       app.set :erb_engine_prefix, ::Tilt
       
+      # After config
       app.after_configuration do
+        # Find the user's prefered engine
+        # Convert symbols to classes
         if erb_engine.is_a? Symbol
           engine = engine.to_s
           engine = engine == "erb" ? "ERB" : engine.camelize
           erb_engine = erb_engine_prefix.const_get("#{engine}Template")
         end
         
+        # Tell Tilt to use the preferred engine
         ::Tilt.prefer(erb_engine)
       end
     end
diff --git a/middleman-more/lib/middleman-more.rb b/middleman-more/lib/middleman-more.rb
index 69ccc8a1..b48daac0 100644
--- a/middleman-more/lib/middleman-more.rb
+++ b/middleman-more/lib/middleman-more.rb
@@ -3,8 +3,6 @@ libdir = File.expand_path(File.dirname(__FILE__))
 $LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
 
 require "middleman-core"
-require "sass"
-require "coffee_script"
 
 # Top-level Middleman object
 module Middleman
@@ -42,6 +40,7 @@ module Middleman
     autoload :MinifyJavascript,    "middleman-more/extensions/minify_javascript"
   end
   
+  require "coffee_script"
   Base.register Middleman::Renderers::Haml
   Base.register Middleman::Renderers::Sass
   Base.register Middleman::Renderers::Markdown
@@ -54,6 +53,7 @@ module Middleman
   # Sprockets asset handling
   Base.register Middleman::CoreExtensions::Sprockets
   
+  # Register the optional extensions
   Extensions.register(:cache_buster) { 
     ::Middleman::Extensions::CacheBuster }
   Extensions.register(:minify_css) { 
diff --git a/middleman-more/lib/middleman-more/core_extensions/compass.rb b/middleman-more/lib/middleman-more/core_extensions/compass.rb
index cbbf8a66..55215075 100644
--- a/middleman-more/lib/middleman-more/core_extensions/compass.rb
+++ b/middleman-more/lib/middleman-more/core_extensions/compass.rb
@@ -4,7 +4,8 @@ module Middleman::CoreExtensions::Compass
   
   # Extension registered
   class << self
-    # @private
+    
+    # Once registered
     def registered(app)
       require "compass"
       
diff --git a/middleman-more/lib/middleman-more/core_extensions/sprockets.rb b/middleman-more/lib/middleman-more/core_extensions/sprockets.rb
index 554c39ff..370534ea 100644
--- a/middleman-more/lib/middleman-more/core_extensions/sprockets.rb
+++ b/middleman-more/lib/middleman-more/core_extensions/sprockets.rb
@@ -1,9 +1,15 @@
-require 'pathname'
+# Require gem
 require "sprockets"
 
+# Sprockets extension
 module Middleman::CoreExtensions::Sprockets
+  
+  # Setup extension
   class << self
+    
+    # Once registered
     def registered(app)
+      # Default compression to off
       app.set :js_compressor, false
       app.set :css_compressor, false
       
@@ -19,9 +25,12 @@ module Middleman::CoreExtensions::Sprockets
         end
       end
       
+      # Once Middleman is setup
       app.ready do
+        # Create sprockets env for JS
         js_env = Middleman::CoreExtensions::Sprockets::JavascriptEnvironment.new(self)
 
+        # Add any gems with vendor/assets/javascripts to paths
         vendor_dir = File.join("vendor", "assets", "javascripts")
         gems_with_js = ::Middleman.rubygems_latest_specs.select do |spec|
           ::Middleman.spec_has_file?(spec, vendor_dir)
@@ -29,6 +38,7 @@ module Middleman::CoreExtensions::Sprockets
           js_env.append_path File.join(spec.full_gem_path, vendor_dir)
         end
 
+        # Add any gems with app/assets/javascripts to paths
         app_dir = File.join("app", "assets", "javascripts")
         gems_with_js = ::Middleman.rubygems_latest_specs.select do |spec|
           ::Middleman.spec_has_file?(spec, app_dir)
@@ -36,21 +46,26 @@ module Middleman::CoreExtensions::Sprockets
           js_env.append_path File.join(spec.full_gem_path, app_dir)
         end
 
-        # add paths to js_env (vendor/assets/javascripts)
+        # Intercept requests to /javascripts and pass to sprockets
         map "/#{js_dir}" do
           run js_env
         end
 
+        # Setup Sprockets Sass options
         sass.each { |k, v| ::Sprockets::Sass.options[k] = v }
+        
+        # Create sprockets env for CSS
         css_env = Middleman::CoreExtensions::Sprockets::StylesheetEnvironment.new(self)
          
+        # Add any gems with vendor/assets/stylesheets to paths
         vendor_dir = File.join("vendor", "assets", "stylesheets")
         gems_with_css = ::Middleman.rubygems_latest_specs.select do |spec|
           ::Middleman.spec_has_file?(spec, vendor_dir)
         end.each do |spec|
           css_env.append_path File.join(spec.full_gem_path, vendor_dir)
         end
-  
+        
+        # Add any gems with app/assets/stylesheets to paths
         app_dir = File.join("app", "assets", "stylesheets")
         gems_with_css = ::Middleman.rubygems_latest_specs.select do |spec|
           ::Middleman.spec_has_file?(spec, app_dir)
@@ -58,6 +73,7 @@ module Middleman::CoreExtensions::Sprockets
           css_env.append_path File.join(spec.full_gem_path, app_dir)
         end
         
+        # Intercept requests to /stylesheets and pass to sprockets
         map("/#{css_dir}") do
           run css_env
         end
@@ -66,7 +82,9 @@ module Middleman::CoreExtensions::Sprockets
     alias :included :registered
   end
 
+  # Generic Middleman Sprockets env
   class MiddlemanEnvironment < ::Sprockets::Environment
+    # Setup
     def initialize(app)
       @app = app
       super app.source_dir
@@ -84,19 +102,26 @@ module Middleman::CoreExtensions::Sprockets
       end
     end
     
+    # During development, don't use the asset cache
     def find_asset(path, options = {})
       expire_index! if @app.development?
       super
     end
   end
     
+  # Javascript specific environment
   class JavascriptEnvironment < MiddlemanEnvironment
+    
+    # Init
     def initialize(app)
       super
       
       expire_index!
 
+      # Remove old compressor
       unregister_bundle_processor 'application/javascript', :js_compressor
+      
+      # Register compressor from config
       register_bundle_processor 'application/javascript', :js_compressor do |context, data|
         if context.pathname.to_s =~ /\.min\./
           data
@@ -109,19 +134,26 @@ module Middleman::CoreExtensions::Sprockets
       append_path app.js_dir
     end
     
+    # Clear cache on error
     def javascript_exception_response(exception)
       expire_index!
       super(exception)
     end
   end
   
+  # CSS specific environment
   class StylesheetEnvironment < MiddlemanEnvironment
+    
+    # Init
     def initialize(app)
       super
       
       expire_index!
 
+      # Remove old compressor
       unregister_bundle_processor 'text/css', :css_compressor
+      
+      # Register compressor from config
       register_bundle_processor 'text/css', :css_compressor do |context, data|
         if context.pathname.to_s =~ /\.min\./
           data
@@ -133,7 +165,8 @@ module Middleman::CoreExtensions::Sprockets
       # configure search paths
       append_path app.css_dir
     end
-  
+    
+    # Clear cache on error
     def css_exception_response(exception)
       expire_index!
       super(exception)
diff --git a/middleman-more/lib/middleman-more/extensions/cache_buster.rb b/middleman-more/lib/middleman-more/extensions/cache_buster.rb
index f0ee1a0e..d1d595f4 100755
--- a/middleman-more/lib/middleman-more/extensions/cache_buster.rb
+++ b/middleman-more/lib/middleman-more/extensions/cache_buster.rb
@@ -1,9 +1,18 @@
+# Extension namespace
 module Middleman::Extensions
+  
+  # The Cache Buster extension
   module CacheBuster
+    
+    # Setup extension
     class << self
+      
+      # Once registered
       def registered(app)
+        # Add instance methods to context
         app.send :include, InstanceMethods
       
+        # After compass is setup, make it use the registered cache buster
         app.compass_config do |config|
           config.asset_cache_buster do |path, real_path|
             real_path = real_path.path if real_path.is_a? File
@@ -19,7 +28,12 @@ module Middleman::Extensions
       alias :included :registered
     end
   
+    # Cache buster instance methods
     module InstanceMethods
+      
+      # asset_url override if we're using cache busting
+      # @param [String] path
+      # @param [String] prefix
       def asset_url(path, prefix="")
         http_path = super
 
@@ -55,5 +69,6 @@ module Middleman::Extensions
     end
   end
   
+  # Register the extension
   register :cache_buster, CacheBuster
 end
\ No newline at end of file
diff --git a/middleman-more/lib/middleman-more/extensions/minify_css.rb b/middleman-more/lib/middleman-more/extensions/minify_css.rb
index 206ed89d..a9fa6680 100644
--- a/middleman-more/lib/middleman-more/extensions/minify_css.rb
+++ b/middleman-more/lib/middleman-more/extensions/minify_css.rb
@@ -1,7 +1,15 @@
+# Extensions namespace
 module Middleman::Extensions
+  
+  # Minify CSS Extension 
   module MinifyCss
+    
+    # Setup extension
     class << self
+      
+      # Once registered
       def registered(app)
+        # Tell Sprockets to use the built in CSSMin
         app.after_configuration do
           if !css_compressor
             require "middleman-more/extensions/minify_css/cssmin"
@@ -13,5 +21,6 @@ module Middleman::Extensions
     end
   end
   
+  # Register extension
   register :minify_css, MinifyCss
 end
\ No newline at end of file
diff --git a/middleman-more/lib/middleman-more/extensions/minify_javascript.rb b/middleman-more/lib/middleman-more/extensions/minify_javascript.rb
index decc0d10..e6df04ab 100755
--- a/middleman-more/lib/middleman-more/extensions/minify_javascript.rb
+++ b/middleman-more/lib/middleman-more/extensions/minify_javascript.rb
@@ -1,25 +1,45 @@
+# Extension namespace
 module Middleman::Extensions
+  
+  # Minify Javascript Extension
   module MinifyJavascript
+    
+    # Setup extension
     class << self
+      
+      # Once registered
       def registered(app)
+        
+        # Once config is parsed
         app.after_configuration do
+          
+          # Tell sprockets which compressor to use
           if !js_compressor
             require 'uglifier'
             set :js_compressor, ::Uglifier.new
           end
           
+          # Setup Rack to watch for inline JS
           use InlineJavascriptRack, :compressor => js_compressor
         end
       end
       alias :included :registered
     end
 
+    # Rack middleware to look for JS in HTML and compress it
     class InlineJavascriptRack
+      
+      # Init
+      # @param [Class] app
+      # @param [Hash] options
       def initialize(app, options={})
         @app = app
         @compressor = options[:compressor]
       end
 
+      # Rack interface
+      # @param [Rack::Environmemt] env
+      # @return [Array]
       def call(env)
         status, headers, response = @app.call(env)
 
@@ -52,5 +72,6 @@ module Middleman::Extensions
     end
   end
   
+  # Register extension
   register :minify_javascript, MinifyJavascript
 end
\ No newline at end of file
diff --git a/middleman-more/lib/middleman-more/extensions/relative_assets.rb b/middleman-more/lib/middleman-more/extensions/relative_assets.rb
index cfade963..56695efb 100755
--- a/middleman-more/lib/middleman-more/extensions/relative_assets.rb
+++ b/middleman-more/lib/middleman-more/extensions/relative_assets.rb
@@ -1,17 +1,32 @@
+# Extension namespace
 module Middleman::Extensions
+  
+  # Relative Assets extension
   module RelativeAssets
+    
+    # Setup extension
     class << self
+      
+      # Once registered
       def registered(app)
+        # Tell compass to use relative assets
         app.compass_config do |config|
           config.relative_assets = true
         end
       
+        # Include instance methods
         app.send :include, InstanceMethods
       end
       alias :included :registered
     end
   
+    # Relative Assets instance method
     module InstanceMethods
+      
+      # asset_url override for relative assets
+      # @param [String] path
+      # @param [String] prefix
+      # @return [String]
       def asset_url(path, prefix="")
         begin
           prefix = images_dir if prefix == http_images_path
@@ -42,5 +57,6 @@ module Middleman::Extensions
     end
   end
   
+  # Register extension
   register :relative_assets, RelativeAssets
 end
\ No newline at end of file
diff --git a/middleman-more/lib/middleman-more/renderers/haml.rb b/middleman-more/lib/middleman-more/renderers/haml.rb
index fdd758cd..96989063 100644
--- a/middleman-more/lib/middleman-more/renderers/haml.rb
+++ b/middleman-more/lib/middleman-more/renderers/haml.rb
@@ -1,9 +1,17 @@
+# Require gem
+require "haml"
+  
+# Haml Renderer
 module Middleman::Renderers::Haml
+  
+  # Setup extension
   class << self
+    # Once registered
     def registered(app)
-      require "haml"
+      # Add haml helpers to context
       app.send :include, ::Haml::Helpers
       
+      # Setup haml helper paths
       app.ready do
         init_haml_helpers
       end
diff --git a/middleman-more/lib/middleman-more/renderers/liquid.rb b/middleman-more/lib/middleman-more/renderers/liquid.rb
index 1d8e4258..3aa2dad6 100644
--- a/middleman-more/lib/middleman-more/renderers/liquid.rb
+++ b/middleman-more/lib/middleman-more/renderers/liquid.rb
@@ -1,14 +1,23 @@
+# Liquid Renderer
 module Middleman::Renderers::Liquid
+  
+  # Setup extension
   class << self
+    
+    # Once registerd
     def registered(app)
       # Liquid is not included in the default gems,
       # but we'll support it if available.
       begin
+        
+        # Require Gem
         require "liquid"
         
+        # After config, setup liquid partial paths
         app.after_configuration do
           Liquid::Template.file_system = Liquid::LocalFileSystem.new(source_dir)
             
+          # Convert data object into a hash for liquid
           provides_metadata %r{\.liquid$} do |path|
             { :locals => { :data => data.to_h } }
           end
diff --git a/middleman-more/lib/middleman-more/renderers/markdown.rb b/middleman-more/lib/middleman-more/renderers/markdown.rb
index 163ac87e..7ef2b43c 100644
--- a/middleman-more/lib/middleman-more/renderers/markdown.rb
+++ b/middleman-more/lib/middleman-more/renderers/markdown.rb
@@ -1,6 +1,12 @@
+# Markdown renderer
 module Middleman::Renderers::Markdown
+  
+  # Setup extension
   class << self
+    
+    # Once registered
     def registered(app)
+      # Require redcarpet gem
       require "redcarpet"
       
       # Forcably disable Redcarpet1 support.
@@ -8,17 +14,24 @@ module Middleman::Renderers::Markdown
       # layer disables extensions.
       Object.send(:remove_const, :RedcarpetCompat) if defined? ::RedcarpetCompat
       
+      # Set our preference for a markdown engine
       app.set :markdown_engine, :redcarpet
       app.set :markdown_engine_prefix, ::Tilt
       
+      # Once configuration is parsed
       app.after_configuration do
+        
+        # Look for the user's preferred engine
         unless markdown_engine.nil?
+          
+          # Map symbols to classes
           if markdown_engine.is_a? Symbol
             engine = engine.to_s
             engine = engine == "rdiscount" ? "RDiscount" : engine.camelize
             markdown_engine = markdown_engine_prefix.const_get("#{engine}Template")
           end
         
+          # Tell tilt to use that engine
           ::Tilt.prefer(markdown_engine)
         end
       end
diff --git a/middleman-more/lib/middleman-more/renderers/sass.rb b/middleman-more/lib/middleman-more/renderers/sass.rb
index d536a60f..be8c5cc1 100644
--- a/middleman-more/lib/middleman-more/renderers/sass.rb
+++ b/middleman-more/lib/middleman-more/renderers/sass.rb
@@ -1,8 +1,15 @@
+# Pull in gems
+require "sass"
 require "sprockets"
 require "sprockets-sass"
 
+# Sass renderer
 module Middleman::Renderers::Sass
+  
+  # Setup extension
   class << self
+    
+    # Once registered
     def registered(app)
       # Default sass options
       app.set :sass, {}
@@ -10,8 +17,13 @@ module Middleman::Renderers::Sass
     alias :included :registered
   end
   
+  # A SassTemplate for Sprockets/Tilt which outputs debug messages
   class SassPlusCSSFilenameTemplate < ::Sprockets::Sass::SassTemplate
+    
     # Add exception messaging
+    # @param [Class] context
+    # @param [Hash] locals
+    # @return [String]
     def evaluate(context, locals, &block)
       begin
         super
@@ -21,6 +33,8 @@ module Middleman::Renderers::Sass
     end
   
   protected
+    # Change Sass path, for url functions, to the build folder if we're building
+    # @return [Hash]
     def sass_options
       location_of_sass_file = if @context.build?
         File.expand_path(@context.build_dir, @context.root)
@@ -35,18 +49,27 @@ module Middleman::Renderers::Sass
       super.merge(:css_filename => css_filename)
     end
   end
+  
+  # Tell Sprockets to use our custom Sass template
   ::Sprockets.register_engine ".sass", SassPlusCSSFilenameTemplate
+  
+  # Tell Tilt to use it as well (for inline sass blocks)
   ::Tilt.register 'sass', SassPlusCSSFilenameTemplate
   ::Tilt.prefer(SassPlusCSSFilenameTemplate)
   
+  # SCSS version of the above template
   class ScssPlusCSSFilenameTemplate < SassPlusCSSFilenameTemplate
     # Define the expected syntax for the template
+    # @return [Symbol]
     def syntax
       :scss
     end
   end
   
+  # Tell Sprockets to use our custom Scss template
   ::Sprockets.register_engine ".scss", ScssPlusCSSFilenameTemplate
+  
+  # Tell Tilt to use it as well (for inline scss blocks)
   ::Tilt.register 'scss', ScssPlusCSSFilenameTemplate
   ::Tilt.prefer(ScssPlusCSSFilenameTemplate)
 end
\ No newline at end of file
diff --git a/middleman-more/lib/middleman-more/renderers/slim.rb b/middleman-more/lib/middleman-more/renderers/slim.rb
index 1d3b0838..d744452c 100644
--- a/middleman-more/lib/middleman-more/renderers/slim.rb
+++ b/middleman-more/lib/middleman-more/renderers/slim.rb
@@ -1,11 +1,18 @@
+# Slim renderer
 module Middleman::Renderers::Slim
+  
+  # Setup extension
   class << self
+    
+    # Once registered
     def registered(app)
       # Slim is not included in the default gems,
       # but we'll support it if available.
       begin
+        # Load gem
         require "slim"
         
+        # Setup Slim options to work with partials
         Slim::Engine.set_default_options(:buffer => '@_out_buf', :generator => Temple::Generators::StringBuffer) if defined?(Slim)
       rescue LoadError
       end