more rdoc

.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
+--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

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
 ====

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
@@ -227,9 +227,6 @@ module Middleman
       opts[:app] = app_class
       opts[:server] = 'thin'
 
-      # require "thin"
-      # ::Thin::Logging.silent = true if options[:debug] != "true"
-
       server = ::Rack::Server.new(opts)
       server.start
       server

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 [Symbol] type File extension
-  # @param [String] Mime type
+  # @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

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)

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]
       

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

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 = {}
       
@@ -135,6 +194,11 @@ module Middleman::CoreExtensions::Data
     end
   
   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)

lib/middleman/templates.rb

@@ -10,17 +10,19 @@ module Middleman::Templates
     
     # 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")
       

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")

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")

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

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")

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