From 96bdd46552741c34f4322987e47c243be653d48d Mon Sep 17 00:00:00 2001
From: Thomas Reynolds <me@tdreyno.com>
Date: Sat, 17 Dec 2011 20:12:13 -0800
Subject: [PATCH] more rdoc

---
 .yardopts                                | 10 ++--
 CHANGELOG.md                             |  1 +
 lib/middleman.rb                         |  5 +-
 lib/middleman/base.rb                    | 24 +++++++--
 lib/middleman/core_extensions/assets.rb  |  1 +
 lib/middleman/core_extensions/builder.rb | 18 +++++++
 lib/middleman/core_extensions/compass.rb |  7 ++-
 lib/middleman/core_extensions/data.rb    | 68 +++++++++++++++++++++++-
 lib/middleman/templates.rb               | 16 ++++--
 lib/middleman/templates/default.rb       |  4 +-
 lib/middleman/templates/html5.rb         |  4 +-
 lib/middleman/templates/local.rb         |  4 +-
 lib/middleman/templates/mobile.rb        |  4 +-
 lib/middleman/version.rb                 |  4 ++
 14 files changed, 147 insertions(+), 23 deletions(-)

diff --git a/.yardopts b/.yardopts
index 59b574b0..5f7ae80d 100644
--- a/.yardopts
+++ b/.yardopts
@@ -1,7 +1,11 @@
 lib/**/*.rb 
---exclude lib/middleman/vendor 
+--exclude lib/middleman/vendor/
 --exclude lib/middleman/extensions/automatic_image_sizes/fastimage.rb 
 --exclude lib/middleman/extensions/minify_css/cssmin.rb
 --exclude lib/middleman/step_definitions
---exclude lib/middleman/step_definitions.rb
---no-private
\ No newline at end of file
+--exclude lib/middleman/templates/default/
+--exclude lib/middleman/templates/html5/
+--exclude lib/middleman/templates/mobile/
+--exclude lib/middleman/templates/shared/
+--no-private
+--hide-void-return
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a23c2a6f..cf8622b4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@
 * Activate mobile html5boilerplate template
 * Update to Redcarpet for Markdown (breaks Haml :markdown filter)
 * Return correct exit codes (0 for success, 1 for failure) from CLI
+* Yard code docs: http://rubydoc.info/github/tdreyno/middleman
 
 2.0.14
 ====
diff --git a/lib/middleman.rb b/lib/middleman.rb
index 8944a11e..5f6a02cf 100755
--- a/lib/middleman.rb
+++ b/lib/middleman.rb
@@ -157,7 +157,7 @@ module Middleman
   class << self
     
     # Where to look for custom templates
-    # @returns [String]
+    # @return [String]
     def templates_path
       File.join(File.expand_path("~/"), ".middleman")
     end
@@ -226,9 +226,6 @@ module Middleman
       app_class = options[:app] ||= ::Middleman.server.inst
       opts[:app] = app_class
       opts[:server] = 'thin'
-    
-      # require "thin"
-      # ::Thin::Logging.silent = true if options[:debug] != "true"
 
       server = ::Rack::Server.new(opts)
       server.start
diff --git a/lib/middleman/base.rb b/lib/middleman/base.rb
index 27ca2c88..a41741a9 100644
--- a/lib/middleman/base.rb
+++ b/lib/middleman/base.rb
@@ -91,6 +91,7 @@ class Middleman::Base
     # Use Rack middleware
     #
     # @param [Class] Middleware
+    # @return [void]
     def use(middleware, *args, &block)
       @middleware ||= []
       @middleware << [middleware, args, block]
@@ -99,6 +100,7 @@ class Middleman::Base
     # Add Rack App mapped to specific path
     #
     # @param [String] Path to map
+    # @return [void]
     def map(map, &block)
       @mappings ||= []
       @mappings << [map, block]
@@ -106,6 +108,7 @@ class Middleman::Base
     
     # Mix-in helper methods. Accepts either a list of Modules
     # and/or a block to be evaluated
+    # @return [void]
     def helpers(*extensions, &block)
       class_eval(&block)   if block_given?
       include(*extensions) if extensions.any?
@@ -123,6 +126,7 @@ class Middleman::Base
     #
     # @param [Symbol] Unique key name
     # @param Default value
+    # @return [void]
     def set(key, value)
       @defaults ||= {}
       @defaults[key] = value
@@ -133,6 +137,7 @@ class Middleman::Base
   #
   # @param [Symbol] Name of the attribue
   # @param Attribute value
+  # @return [void]
   def set(key, value=nil, &block)
     setter = "#{key}=".to_sym
     self.class.send(:attr_accessor, key) if !respond_to?(setter)
@@ -263,6 +268,10 @@ class Middleman::Base
     @_current_path
   end
   
+  # Set the current path
+  #
+  # @param [String] path The new current path
+  # @return [void]
   def current_path=(path)
     @_current_path = path
     @request = Thor::CoreExt::HashWithIndifferentAccess.new({ :path => path })
@@ -423,7 +432,7 @@ class Middleman::Base
   # Expand a path to include the index file if it's a directory
   #
   # @private
-  # @param [String] Request path
+  # @param [String] path Request path
   # @return [String] Path with index file if necessary
   def full_path(path)
     cache.fetch(:full_path, path) do
@@ -437,8 +446,9 @@ class Middleman::Base
   
   # Add a new mime-type for a specific extension
   #
-  # @param [Symbol] File extension
-  # @param [String] Mime type
+  # @param [Symbol] type File extension
+  # @param [String] value Mime type
+  # @return [void]
   def mime_type(type, value=nil)
     return type if type.nil? || type.to_s.include?('/')
     type = ".#{type}" unless type.to_s[0] == ?.
@@ -461,18 +471,20 @@ protected
   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
   
   # Immediately send static file
   #
-  # @param [String] File to send
+  # @param [String] path File to send
   def send_file(path)
     extension = File.extname(path)
     matched_mime = mime_type(extension)
@@ -488,7 +500,9 @@ protected
   
   # Set the content type for the current request
   #
-  # @param [String] Content type
+  # @param [String] type Content type
+  # @param [Hash] params
+  # @return [void]
   def content_type(type = nil, params={})
     return res['Content-Type'] unless type
     default = params.delete :default
diff --git a/lib/middleman/core_extensions/assets.rb b/lib/middleman/core_extensions/assets.rb
index 49c46f54..8db7e1ba 100644
--- a/lib/middleman/core_extensions/assets.rb
+++ b/lib/middleman/core_extensions/assets.rb
@@ -21,6 +21,7 @@ module Middleman::CoreExtensions::Assets
     #
     # @param [String] path The path (such as "photo.jpg")
     # @param [String] prefix The type prefix (such as "images")
+    # @return [String] The fully qualified asset url
     def asset_url(path, prefix="")
       # Don't touch assets which already have a full path
       path.include?("://") ? path : File.join(http_prefix, prefix, path)
diff --git a/lib/middleman/core_extensions/builder.rb b/lib/middleman/core_extensions/builder.rb
index 97076638..c3cd987a 100644
--- a/lib/middleman/core_extensions/builder.rb
+++ b/lib/middleman/core_extensions/builder.rb
@@ -1,13 +1,22 @@
+# Convenience methods to allow config.rb to talk to the Builder
 module Middleman::CoreExtensions::Builder
+  
+  # Extension registered
   class << self
+    # @private
     def registered(app)
       app.define_hook :after_build
       app.extend ClassMethods
       app.send :include, InstanceMethods
     end
+    alias :included :registered
   end
   
+  # Build Class Methods
   module ClassMethods
+    # Get a list of callbacks which can modify a files build path
+    #
+    # @return [Array<Proc>]
     def build_reroute(&block)
       @build_rerouters ||= []
       @build_rerouters << block if block_given?
@@ -15,11 +24,20 @@ module Middleman::CoreExtensions::Builder
     end
   end
   
+  # 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
+    # @param [String] request_path The current request path of the file
+    # @return [Array<String>] The new values
     def reroute_builder(destination, request_path)
       result = [destination, request_path]
       
diff --git a/lib/middleman/core_extensions/compass.rb b/lib/middleman/core_extensions/compass.rb
index 2b48fb68..97f8b5f1 100644
--- a/lib/middleman/core_extensions/compass.rb
+++ b/lib/middleman/core_extensions/compass.rb
@@ -1,5 +1,10 @@
+# Forward the settings on config.rb and the result of registered extensions
+# to Compass
 module Middleman::CoreExtensions::Compass
+  
+  # Extension registered
   class << self
+    # @private
     def registered(app)
       require "compass"
       
@@ -47,7 +52,7 @@ module Middleman::CoreExtensions::Compass
           config.output_style = :nested
         end
         
-        # Required for relative paths
+        # Change paths when in build mode. Required for relative paths
         configure :build do
           ::Compass.configuration do |config|
             config.environment = :production
diff --git a/lib/middleman/core_extensions/data.rb b/lib/middleman/core_extensions/data.rb
index c6f5190b..2bccb7e2 100755
--- a/lib/middleman/core_extensions/data.rb
+++ b/lib/middleman/core_extensions/data.rb
@@ -1,9 +1,17 @@
+# Data formats
 require "yaml"
 require "active_support/json"
+
+# Using Thor's indifferent hash access
 require "thor"
 
+# The data extension parses YAML and JSON files in the data/ directory
+# and makes them available to config.rb, templates and extensions
 module Middleman::CoreExtensions::Data
+  
+  # Extension registered
   class << self
+    # @private
     def registered(app)
       app.set :data_dir, "data"
       app.send :include, InstanceMethods
@@ -11,7 +19,10 @@ module Middleman::CoreExtensions::Data
     alias :included :registered
   end
   
+  # Instance methods
   module InstanceMethods
+    # Setup data files before anything else so they are available when
+    # parsing config.rb
     def initialize
       file_changed DataStore.matcher do |file|
         data.touch_file(file) if file.match(%r{^#{data_dir}\/})
@@ -24,43 +35,77 @@ module Middleman::CoreExtensions::Data
       super
     end
     
+    # The data object
+    #
+    # @return [DataStore]
     def data
       @data ||= DataStore.new(self)
     end
 
     # Makes a hash available on the data var with a given name
+    #
+    # @param [Symbol] name Name of the data, used for namespacing
+    # @param [Hash] content The content for this data
+    # @return [void]
     def data_content(name, content)
       DataStore.data_content(name, content)
     end
 
     # Makes a hash available on the data var with a given name
+    #
+    # @param [Symbol] name Name of the data, used for namespacing
+    # @return [void]
     def data_callback(name, &block)
       DataStore.data_callback(name, block)
     end
   end
   
+  # The core logic behind the data extension.
   class DataStore
+    
+    # Static methods
     class << self
+      
+      # The regex which tells Middleman which files are for data
+      #
+      # @return [Regexp]
       def matcher
         %r{[\w-]+\.(yml|yaml|json)$}
       end
 
+      # Store static data hash
+      #
+      # @param [Symbol] name Name of the data, used for namespacing
+      # @param [Hash] content The content for this data
+      # @return [void]
       def data_content(name, content)
         @@local_sources ||= {}
         @@local_sources[name.to_s] = content
       end
 
+      # Store callback-based data
+      #
+      # @param [Symbol] name Name of the data, used for namespacing
+      # @param [Proc] proc The callback which will return data
+      # @return [void]
       def data_callback(name, proc)
         @@callback_sources ||= {}
         @@callback_sources[name.to_s] = proc
       end
     end
     
+    # Setup data store
+    #
+    # @param [Middleman::Base] app The current instance of Middleman
     def initialize(app)
       @app = app
       @local_data = {}
     end
     
+    # Update the internal cache for a given file path
+    #
+    # @param [String] file The file to be re-parsed
+    # @return [void]
     def touch_file(file)
       file = File.expand_path(file, @app.root)
       extension = File.extname(file)
@@ -74,16 +119,23 @@ module Middleman::CoreExtensions::Data
         return
       end
 
-      # @app.logger.debug :data_update, Time.now, basename if @app.logging?
       @local_data[basename] = recursively_enhance(data)
     end
     
+    # Remove a given file from the internal cache
+    #
+    # @param [String] file The file to be cleared
+    # @return [void]
     def remove_file(file)
       extension = File.extname(file)
       basename  = File.basename(file, extension)
       @local_data.delete(basename) if @local_data.has_key?(basename)
     end
     
+    # Get a hash hash from either internal static data or a callback
+    #
+    # @param [String, Symbol] path The name of the data namespace
+    # @return [Hash, nil]
     def data_for_path(path)
       response = nil
       
@@ -99,6 +151,10 @@ module Middleman::CoreExtensions::Data
       response
     end
     
+    # "Magically" find namespaces of data if they exist
+    #
+    # @param [String] path The namespace to search for
+    # @return [Hash, nil]
     def method_missing(path)
       if @local_data.has_key?(path.to_s)
         return @local_data[path.to_s]
@@ -113,6 +169,9 @@ module Middleman::CoreExtensions::Data
       super
     end
     
+    # Convert all the data into a static hash
+    #
+    # @return [Hash]
     def to_h
       data = {}
       
@@ -134,7 +193,12 @@ module Middleman::CoreExtensions::Data
       data
     end
   
-  private
+  private 
+    # Recursively convert a normal Hash into a HashWithIndifferentAccess
+    #
+    # @private
+    # @param [Hash] data Normal hash
+    # @return [Thor::CoreExt::HashWithIndifferentAccess]
     def recursively_enhance(data)
       if data.is_a? Hash
         data = Thor::CoreExt::HashWithIndifferentAccess.new(data)
diff --git a/lib/middleman/templates.rb b/lib/middleman/templates.rb
index 4825833e..0433312a 100644
--- a/lib/middleman/templates.rb
+++ b/lib/middleman/templates.rb
@@ -9,18 +9,20 @@ module Middleman::Templates
   class << self
     
     # Get list of registered templates and add new ones
+    # 
+    #     Middleman::Templates.register(:ext_name, klass)
     #
     # @param [Symbol] name The name of the template
     # @param [Class] klass The class to be executed for this template
     # @return [Hash] List of registered templates
-    def registered(*args)
+    def register(*args)
       @_template_mappings ||= {}
       @_template_mappings[args[0]] = args[1] if args.length == 2
       @_template_mappings
     end
     
     # Middleman::Templates.register(name, klass)
-    alias :register :registered
+    alias :registered :register
   end
   
   # Base Template class. Handles basic options and paths.
@@ -44,14 +46,20 @@ module Middleman::Templates
     
     # Output a config.ru file for Rack if --rack is passed
     class_option :rack, :type => :boolean, :default => false
-    def generate_rack
+    
+    # Write a Rack config.ru file for project
+    # @return [void]
+    def generate_rack!
       return unless options[:rack]
       template "shared/config.ru", File.join(location, "config.ru")
     end
     
     # Output a Gemfile file for Bundler if --bundler is passed
     class_option :bundler, :type => :boolean, :default => false
-    def generate_bundler
+    
+    # Write a Bundler Gemfile file for project
+    # @return [void]
+    def generate_bundler!
       return unless options[:bundler]
       template "shared/Gemfile.tt", File.join(location, "Gemfile")
       
diff --git a/lib/middleman/templates/default.rb b/lib/middleman/templates/default.rb
index 9931aa41..a810bdd9 100644
--- a/lib/middleman/templates/default.rb
+++ b/lib/middleman/templates/default.rb
@@ -2,12 +2,14 @@
 class Middleman::Templates::Default < Middleman::Templates::Base
   
   # Template files are relative to this file
+  # @return [String]
   def self.source_root
     File.dirname(__FILE__)
   end
   
   # Actually output the files
-  def build_scaffold
+  # @return [void]
+  def build_scaffold!
     template "shared/config.tt", File.join(location, "config.rb")
     copy_file "default/source/index.html.erb", File.join(location, "source/index.html.erb")
     copy_file "default/source/layout.erb", File.join(location, "source/layout.erb")
diff --git a/lib/middleman/templates/html5.rb b/lib/middleman/templates/html5.rb
index 72f11f86..d7872cda 100644
--- a/lib/middleman/templates/html5.rb
+++ b/lib/middleman/templates/html5.rb
@@ -7,12 +7,14 @@ class Middleman::Templates::Html5 < Middleman::Templates::Base
   class_option :images_dir, :default => "img"
 
   # Templates are relative to this file
+  # @return [String]
   def self.source_root
     File.dirname(__FILE__)
   end
   
   # Output the files
-  def build_scaffold
+  # @return [void]
+  def build_scaffold!
     template "shared/config.tt", File.join(location, "config.rb")
     directory "html5/source", File.join(location, "source")
     empty_directory File.join(location, "source")
diff --git a/lib/middleman/templates/local.rb b/lib/middleman/templates/local.rb
index 1ea76ad3..d818790c 100644
--- a/lib/middleman/templates/local.rb
+++ b/lib/middleman/templates/local.rb
@@ -2,12 +2,14 @@
 class Middleman::Templates::Local < Middleman::Templates::Base
   
   # Look for templates in ~/.middleman
+  # @return [String]
   def self.source_root
     Middleman.templates_path
   end
 
   # Just copy from the template path
-  def build_scaffold
+  # @return [void]
+  def build_scaffold!
     directory options[:template].to_s, location
   end  
 end
diff --git a/lib/middleman/templates/mobile.rb b/lib/middleman/templates/mobile.rb
index bc9e6e35..0b88f100 100644
--- a/lib/middleman/templates/mobile.rb
+++ b/lib/middleman/templates/mobile.rb
@@ -7,12 +7,14 @@ class Middleman::Templates::Mobile < Middleman::Templates::Base
   class_option :images_dir, :default => "img"
 
   # Template files are relative to this file
+  # @return [String]
   def self.source_root
     File.dirname(__FILE__)
   end
   
   # Output the files
-  def build_scaffold
+  # @return [void]
+  def build_scaffold!
     template "shared/config.tt", File.join(location, "config.rb")
     directory "mobile/source", File.join(location, "source")
     empty_directory File.join(location, "source")
diff --git a/lib/middleman/version.rb b/lib/middleman/version.rb
index 8678de25..0052fed6 100644
--- a/lib/middleman/version.rb
+++ b/lib/middleman/version.rb
@@ -2,8 +2,12 @@
 require "rubygems"
 
 module Middleman
+  # Current Version
+  # @return [String]
   VERSION = "3.0.0.alpha.4"
   
+  # Parsed version for RubyGems
   # @private
+  # @return [String]
   GEM_VERSION = ::Gem::Version.create(VERSION)
 end