From 2965e3709d515ad1a1fd15af6da8d8113e3ccfd8 Mon Sep 17 00:00:00 2001
From: Thomas Reynolds <me@tdreyno.com>
Date: Wed, 2 May 2012 11:13:06 -0700
Subject: [PATCH] Yard doc cleanup

---
 Gemfile                                          |  2 +-
 Rakefile                                         | 15 ++++++++-------
 gem_rake_helper.rb                               |  4 ++--
 .../middleman-core/core_extensions/extensions.rb |  7 ++++---
 .../core_extensions/front_matter.rb              |  8 ++++----
 middleman-core/lib/middleman-core/extensions.rb  |  4 ++--
 .../middleman-core/sitemap/extensions/ignores.rb | 16 +++++++++++++---
 .../lib/middleman-core/sitemap/store.rb          |  5 +++--
 middleman-core/lib/middleman-core/templates.rb   |  4 ++--
 middleman-core/lib/middleman-core/util.rb        |  2 +-
 10 files changed, 40 insertions(+), 27 deletions(-)

diff --git a/Gemfile b/Gemfile
index e4c7586f..a7f19a1a 100644
--- a/Gemfile
+++ b/Gemfile
@@ -7,7 +7,7 @@ group :development do
   gem "rake",     "~> 0.9.2"
   gem "rspec",    "~> 2.7"
   gem "rdoc",     "~> 3.9"
-  # gem "yard"
+  gem "yard",     "~> 0.8.0"
 end
   
 group :test do
diff --git a/Rakefile b/Rakefile
index 1435472a..810d430d 100644
--- a/Rakefile
+++ b/Rakefile
@@ -1,7 +1,6 @@
 require 'rubygems'  unless defined?(Gem)
 # require 'fileutils' unless defined?(FileUtils)
 require 'rake'
-# require 'yard'
 
 require File.expand_path("../middleman-core/lib/middleman-core/version.rb", __FILE__)
 
@@ -74,6 +73,13 @@ task :publish => :push do
   Rake::Task["clean"].invoke
 end
 
+desc "Generate documentation for all middleman gems"
+task :doc do
+  GEM_PATHS.each do |g|
+    sh "cd #{File.join(ROOT, g)} && #{Gem.ruby} -S rake yard"
+  end
+end
+
 desc "Run tests for all middleman gems"
 task :test do
   GEM_PATHS.each do |g|
@@ -82,9 +88,4 @@ task :test do
 end
 
 desc "Run tests for all middleman gems"
-task :default => :test
-
-# desc "Generate documentation"
-# task :doc do
-#   YARD::CLI::Yardoc.new.run
-# end
\ No newline at end of file
+task :default => :test
\ No newline at end of file
diff --git a/gem_rake_helper.rb b/gem_rake_helper.rb
index 22fea587..5cb71c65 100644
--- a/gem_rake_helper.rb
+++ b/gem_rake_helper.rb
@@ -1,7 +1,7 @@
 require 'rubygems' unless defined?(Gem)
 require 'rake'
 require 'cucumber/rake/task'
-# require 'yard'
+require 'yard'
 
 require 'bundler'
 Bundler::GemHelper.install_tasks :name => GEM_NAME
@@ -20,6 +20,6 @@ Cucumber::Rake::Task.new(:test, 'Run features that should pass') do |t|
   t.cucumber_opts = "--color --tags ~@wip --strict --format #{ENV['CUCUMBER_FORMAT'] || 'Fivemat'}"
 end
 
-# YARD::Rake::YardocTask.new
+YARD::Rake::YardocTask.new
 
 task :default => :test
\ No newline at end of file
diff --git a/middleman-core/lib/middleman-core/core_extensions/extensions.rb b/middleman-core/lib/middleman-core/core_extensions/extensions.rb
index 4889d1f8..f5a22bc7 100644
--- a/middleman-core/lib/middleman-core/core_extensions/extensions.rb
+++ b/middleman-core/lib/middleman-core/core_extensions/extensions.rb
@@ -62,15 +62,16 @@ module Middleman::CoreExtensions::Extensions
     
     # Alias `extensions` to access registered extensions
     #
-    # @return [Array<Module]
+    # @return [Array<Module>]
     def extensions
       @extensions ||= []
     end
     
     # Register a new extension
     # 
-    # @param [Array<Module>] new_extensions Extension modules to register
-    # @return [Array<Module]
+    # @param [Module] extension Extension modules to register
+    # @param [Hash] options Per-extension options hash
+    # @return [void]
     def register(extension, options={}, &block)
       @extensions ||= []
       @extensions += [extension]
diff --git a/middleman-core/lib/middleman-core/core_extensions/front_matter.rb b/middleman-core/lib/middleman-core/core_extensions/front_matter.rb
index 77f37548..c863a439 100644
--- a/middleman-core/lib/middleman-core/core_extensions/front_matter.rb
+++ b/middleman-core/lib/middleman-core/core_extensions/front_matter.rb
@@ -102,11 +102,11 @@ module Middleman::CoreExtensions::FrontMatter
       @_frontmatter_extension ||= FrontMatter.new(self)
     end
     
-    # Get the frontmatter for the given params
+    # Get the frontmatter for a given path
     # @param [String] path
-    # @return [Hash, nil]
-    def frontmatter(*args)
-      frontmatter_extension.data(*args)
+    # @return [Hash]
+    def frontmatter(path)
+      frontmatter_extension.data(path)
     end
   end
   
diff --git a/middleman-core/lib/middleman-core/extensions.rb b/middleman-core/lib/middleman-core/extensions.rb
index 550980b0..a7d94b2a 100644
--- a/middleman-core/lib/middleman-core/extensions.rb
+++ b/middleman-core/lib/middleman-core/extensions.rb
@@ -171,8 +171,8 @@ module Middleman
     # to discover extensions and Sprockets-supporting gems.
     #
     # @private
-    # @param [Gem::Specification]
-    # @param [String] Path to look for
+    # @param [Gem::Specification] spec
+    # @param [String] path Path to look for
     # @return [Boolean] Whether the file exists
     def spec_has_file?(spec, path)
       full_path = File.join(spec.full_gem_path, path)
diff --git a/middleman-core/lib/middleman-core/sitemap/extensions/ignores.rb b/middleman-core/lib/middleman-core/sitemap/extensions/ignores.rb
index 602db133..9eca8636 100644
--- a/middleman-core/lib/middleman-core/sitemap/extensions/ignores.rb
+++ b/middleman-core/lib/middleman-core/sitemap/extensions/ignores.rb
@@ -16,7 +16,11 @@ module Middleman::Sitemap::Extensions
       alias :included :registered
     end
     
+    # Helpers methods for Resources
     module ResourceInstanceMethods
+      
+      # Whether the Resource is ignored
+      # @return [Boolean]
       def ignored?
         @app.ignore_manager.ignored?(path) || 
         (!proxy? &&
@@ -25,25 +29,31 @@ module Middleman::Sitemap::Extensions
       end
     end
     
+    # Ignore-related instance methods
     module InstanceMethods
       def ignore_manager
         @_ignore_manager ||= IgnoreManager.new(self)
       end
       
-      def ignore(*args, &block)
-        ignore_manager.ignore(*args, &block)
+      # Ignore a path or add an ignore callback
+      # @param [String, Regexp] path Path glob expression, or path regex
+      # @return [void]
+      def ignore(path=nil, &block)
+        ignore_manager.ignore(path, &block)
       end
     end
     
+    # Class to handle managing ignores
     class IgnoreManager
       def initialize(app)
         @app = app
 
+        # Array of callbacks which can ass ignored
         @ignored_callbacks = []
       end
       
       # Ignore a path or add an ignore callback
-      # @param [String, Regexp] path, path glob expression, or path regex
+      # @param [String, Regexp] path Path glob expression, or path regex
       # @return [void]
       def ignore(path=nil, &block)
         original_callback_size = @ignored_callbacks.size
diff --git a/middleman-core/lib/middleman-core/sitemap/store.rb b/middleman-core/lib/middleman-core/sitemap/store.rb
index da6ec861..3974f9b8 100644
--- a/middleman-core/lib/middleman-core/sitemap/store.rb
+++ b/middleman-core/lib/middleman-core/sitemap/store.rb
@@ -32,8 +32,9 @@ module Middleman::Sitemap
     end
 
     # Register a klass which can manipulate the main site map list
-    # @param [Class] klass
-    # @param [Boolean] immediately_rebuild
+    # @param [Symbol] name Name of the manipulator for debugging
+    # @param [Class, Module] inst Abstract namespace which can update the resource list
+    # @param [Boolean] immediately_rebuild Whether the resource list should be immediately recalculated
     # @return [void]
     def register_resource_list_manipulator(name, inst, immediately_rebuild=true)
       @resource_list_manipulators << [name, inst]
diff --git a/middleman-core/lib/middleman-core/templates.rb b/middleman-core/lib/middleman-core/templates.rb
index 365a76bc..67808cab 100644
--- a/middleman-core/lib/middleman-core/templates.rb
+++ b/middleman-core/lib/middleman-core/templates.rb
@@ -15,9 +15,9 @@ module Middleman::Templates
     # @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 register(*args)
+    def register(name=nil, klass=nil)
       @_template_mappings ||= {}
-      @_template_mappings[args[0]] = args[1] if args.length == 2
+      @_template_mappings[name] = klass if name && klass
       @_template_mappings
     end
     
diff --git a/middleman-core/lib/middleman-core/util.rb b/middleman-core/lib/middleman-core/util.rb
index 7da04a37..09167e29 100644
--- a/middleman-core/lib/middleman-core/util.rb
+++ b/middleman-core/lib/middleman-core/util.rb
@@ -107,4 +107,4 @@ module Middleman
       end
     end
   end
-end
+end
\ No newline at end of file