Adding specs for base directories

Squashed commit of the following:

commit 23c710dd086e1a435d74a3f669927800b4fd45e0
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Tue Mar 24 18:25:28 2009 -0400

    Finished cleaning up configuration specs

commit 27f3a48dd45c40dc2ed9a1523a61f26167bbccb0
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Tue Mar 24 18:18:48 2009 -0400

    Cleaning up remaining specs in report_spec

commit b1f65446c93050f9bc27b3b354c3929892595d05
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Mon Mar 23 10:50:50 2009 -0400

    Added some pending examples to remind me to cleanup later

commit b130ce9f7fe821f3600615da3f15674fd1134557
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Mon Mar 23 10:38:51 2009 -0400

    Added some specs

commit 094193c6f9624d28e9221a81a401e7b7d671631c
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Mon Mar 23 10:38:19 2009 -0400

    Pushed PLATFORM recognition down into MetricFu.configuration

commit a1759b7db57b90746ab8f775602b2d8356b9d935
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Mon Mar 23 10:37:07 2009 -0400

    Removed annoyning autospec duplicate runs

commit 8ee307689c9058ccb41c7c1278df0639f19ba39f
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Sat Mar 21 14:40:10 2009 -0400

    Added a stack of specs

commit 019a9bbe157677099d8a1cd574b0079bed56aded
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Sat Mar 21 14:39:23 2009 -0400

    Refer to method accessor rather than instance variable

commit b560b6181281f780d81120c4318be65ccb2ecd5b
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Sat Mar 21 00:03:59 2009 -0400

    Fixed typo

commit c40e71def250b82e60571ff847f516339f26097b
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Fri Mar 20 23:57:00 2009 -0400

    Ignoring previous_failures.txt generated by rspec

commit bf51ef39661dcf6f46f3c52130873dd31e860095
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Fri Mar 20 23:56:26 2009 -0400

    Added fancy spec.opts

commit 19f045cbf22f80ec4368a571d5e82149b6e7d286
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Fri Mar 20 23:55:59 2009 -0400

    Specced out base_template

commit e7834358615fb981962efca14f49195e2f506af7
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Sun Mar 15 22:29:36 2009 -0400

    Added docs and specs for Generator

commit 875e12a43398568dbf3cbbb29a9f8e05184e3345
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Sun Mar 15 12:05:34 2009 -0400

    Added docs to Generator

commit 34bbb2603cef610b503b85db22f8b4eb38bd726b
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Sun Mar 15 00:16:48 2009 -0400

    Another quick update to the specs

commit d0f4ebc66fa1e414732e29e0e0c0f5189f04d34c
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Sun Mar 15 00:06:07 2009 -0400

    Added specs and docs for Configuration

commit f8ee3cc0979a2601adb2086f579efce0de6557ee
Author: Grant McInnes <grant.mcinnes@eyesopen.ca>
Date:   Wed Feb 25 23:11:15 2009 -0500

    Starting work on specs for MetricFu::Configuration

.gitignore

@@ -1,2 +1,3 @@
+previous_failures.txt
 tmp/*
-metric_fu-*.gem
+metric_fu-*.gem

lib/base/base_template.rb

@@ -1,47 +1,133 @@
 module MetricFu
-class Template
-  attr_accessor :report
-
-  private
-
-  def erbify(section)
-    erb_doc = File.read(template(section))
-    ERB.new(erb_doc).result(binding)
-  end
 
-  def template_exists?(section)
-    File.exist?(template(section))
-  end
+  # The Template class is intended as an abstract class for concrete
+  # template classes to subclass.  It provides a variety of utility
+  # methods to make templating a bit easier.  However, classes do not
+  # have to inherit from here in order to provide a template.  The only
+  # requirement for a template class is that it provides a #write method
+  # to actually write out the template.  See StandardTemplate for an
+  # example.
+  class Template
+    attr_accessor :report
+
+    private
+    # Creates a new erb evaluated result from the passed in section.
+    #
+    # @param section String
+    #   The section name of 
+    #
+    # @return String
+    #   The erb evaluated string
+    def erbify(section)
+      erb_doc = File.read(template(section))
+      ERB.new(erb_doc).result(binding)
+    end
 
-  def create_instance_var(section, contents)
-    instance_variable_set("@#{section}", contents)        
-  end
+    # Determines whether a template file exists for a given section
+    # of the full template.
+    #
+    # @param section String
+    #   The section of the template to check against
+    #
+    # @return Boolean
+    #   Does a template file exist for this section or not?
+    def template_exists?(section)
+      File.exist?(template(section))
+    end
+
+    # Copies an instance variable mimicing the name of the section
+    # we are trying to render, with a value equal to the passed in 
+    # constant.  Allows the concrete template classes to refer to 
+    # that instance variable from their ERB rendering
+    #
+    # @param section String
+    #  The name of the instance variable to create
+    #
+    # @param contents Object
+    #   The value to set as the value of the created instance
+    #   variable
+    def create_instance_var(section, contents)
+      instance_variable_set("@#{section}", contents)        
+    end
 
-  def template(section)
-    File.join(this_directory,  section.to_s + ".html.erb")
-  end
+    # Generates the filename of the template file to load and 
+    # evaluate.  In this case, the path to the template directory +
+    # the section name + .html.erb
+    #
+    # @param section String
+    #   A section of the template to render
+    #
+    # @return String
+    #   A file path
+    def template(section)
+      File.join(this_directory,  section.to_s + ".html.erb")
+    end
 
-  def output_filename(section)
-    section.to_s + ".html"
-  end
+    # Returns the filename that the template will render into for
+    # a given section.  In this case, the section name + '.html'
+    #
+    # @param section String
+    #   A section of the template to render
+    #
+    # @return String
+    #   The output filename
+    def output_filename(section)
+      section.to_s + ".html"
+    end
 
-  def inline_css(css)
-    open(File.join(this_directory, css)) { |f| f.read }      
-  end
-
-  def link_to_filename(name, line = nil)
-    filename = File.expand_path(name)
-    if PLATFORM['darwin']
-      %{<a href="txmt://open/?url=file://#{filename}&line=#{line}">#{name}:#{line}</a>}
-    else
-      %{<a href="file://#{filename}">#{name}:#{line}</a>}
+    # Returns the contents of a given css file in order to 
+    # render it inline into a template.
+    #
+    # @param css String
+    #   The name of a css file to open
+    #
+    # @return String
+    #   The contents of the css file
+    def inline_css(css)
+      open(File.join(this_directory, css)) { |f| f.read }      
+    end
+
+    # Provides a link to open a file through the textmate protocol
+    # on Darwin, or otherwise, a simple file link.
+    #
+    # @param name String
+    #   
+    # @param line Integer
+    #   The line number to link to, if textmate is available.  Defaults
+    #   to nil
+    #
+    # @return String
+    #   An anchor link to a textmate reference or a file reference
+    def link_to_filename(name, line = nil)
+      filename = File.expand_path(name)
+      if MetricFu.configuration.platform.include?('darwin')
+        "<a href='txmt://open/?url=file://" \
+        +"#{filename}&line=#{line}'>#{name}:#{line}</a>"
+      else 
+       "<a href='file://#{filename}'>#{name}:#{line}</a>"
+      end
     end
-  end
 
-  def cycle(first_value, second_value, iteration)
-    return first_value if iteration % 2 == 0
-    return second_value
-  end      
 
-end
+    # Provides a brain dead way to cycle between two values during
+    # an iteration of some sort.  Pass in the first_value, the second_value,
+    # and the cardinality of the iteration.
+    #
+    # @param first_value Object
+    #
+    # @param second_value Object
+    #
+    # @param iteration Integer
+    #   The number of times through the iteration.
+    #
+    # @return Object
+    #   The first_value if iteration is even.  The second_value if
+    #   iteration is odd.
+    def cycle(first_value, second_value, iteration)
+      return first_value if iteration % 2 == 0
+      return second_value
+    end      
+
+
+  end
 end

lib/base/configuration.rb

@@ -1,19 +1,64 @@
 module MetricFu
 
+  # A list of metrics which are available in the MetricFu system.
+  #
+  # These are metrics which have been developed for the system.  Of
+  # course, in order to use these metrics, their respective gems must
+  # be installed on the system.
+  AVAILABLE_METRICS = [:churn, :flog, :flay, :reek, 
+                       :roodi, :saikuro, :rcov]
 
+
+  # The @@configuration class variable holds a global type configuration
+  # object for any parts of the system to use.
   def self.configuration
     @@configuration ||= Configuration.new
   end
 
+  # = Configuration
+  #
+  # The Configuration class, as it sounds, provides methods for
+  # configuring the behaviour of MetricFu.
+  #
+  # == Customization for Rails
+  #
+  # The Configuration class checks for the presence of a
+  # 'config/environment.rb' file.  If the file is present, it assumes
+  # it is running in a Rails project.  If it is, it will:
+  #
+  # * Add 'app' to the @code_dirs directory to include the
+  #   code in the app directory in the processing
+  # * Add :stats to the list of metrics to run to get the Rails stats
+  #   task
+  #
+  # == Customization for CruiseControl.rb
+  #
+  # The Configuration class checks for the presence of a 
+  # 'CC_BUILD_ARTIFACTS' environment variable.  If it's found
+  # it will change the default output directory from the default
+  # "tmp/metric_fu to the directory represented by 'CC_BUILD_ARTIFACTS'
+  #
+  # == Deprications
+  #
+  # The Configuration class checks for several deprecated constants
+  # that were previously used to configure MetricFu.  These include
+  # CHURN_OPTIONS, DIRECTORIES_TO_FLOG, SAIKURO_OPTIONS, 
+  # and MetricFu::SAIKURO_OPTIONS.
+  #
+  # These have been replaced by config.churn, config.flog and
+  # config.saikuro respectively.
   class Configuration
 
-    def initialize
+    def initialize #:nodoc:#
       warn_about_deprecated_config_options
       reset
       add_attr_accessors_to_self
       add_class_methods_to_metric_fu
     end
-
+
+    # Searches through the instance variables of the class and
+    # creates a class method on the MetricFu module to read the value
+    # of the instance variable from the Configuration class.
     def add_class_methods_to_metric_fu
       instance_variables.each do |name|
         method_name = name[1..-1].to_sym
@@ -26,13 +71,19 @@ def self.#{method_name}
       end
     end
 
+    # Searches through the instance variables of the class and creates
+    # an attribute accessor on this instance of the Configuration 
+    # class for each instance variable.
     def add_attr_accessors_to_self
       instance_variables.each do |name|
         method_name = name[1..-1].to_sym
         MetricFu::Configuration.send(:attr_accessor, method_name)
       end
     end
 
+    # Check if certain constants that are deprecated have been
+    # assigned.  If so, warn the user about them, and the 
+    # fact that they will have no effect.
     def warn_about_deprecated_config_options
       if defined?(::MetricFu::CHURN_OPTIONS)
         raise("Use config.churn instead of MetricFu::CHURN_OPTIONS")
@@ -49,26 +100,31 @@ def warn_about_deprecated_config_options
       end
     end
 
-    def self.run()  
+    # This allows us to have a nice syntax like:
+    #
+    #   MetricFu.run do |config|
+    #     config.base_directory = 'tmp/metric_fu'
+    #   end
+    #
+    # See the README for more information on configuration options.
+    def self.run
       yield MetricFu.configuration
     end
-
+
+    # This does the real work of the Configuration class, by setting
+    # up a bunch of instance variables to represent the configuration
+    # of the MetricFu app.
     def reset
       @base_directory = ENV['CC_BUILD_ARTIFACTS'] || 'tmp/metric_fu'
-      @template_directory =  File.join(File.dirname(__FILE__), '..', 'templates')
       @scratch_directory = File.join(@base_directory, 'scratch')
       @output_directory = File.join(@base_directory, 'output')
+      @metric_fu_root_directory = File.join(File.dirname(__FILE__), 
+                                                        '..', '..')
+      @template_directory =  File.join(@metric_fu_root_directory, 
+                                       'lib', 'templates') 
       @template_class = StandardTemplate
-      @rails = File.exist?("config/environment.rb") 
-      @available_metrics =[:churn, :flog,  :flay,
-                          :reek, :roodi, :saikuro, :rcov]
-      if @rails
-        @code_dirs = ['app', 'lib']
-        @metrics = @available_metrics + [:stats]
-      else
-        @code_dirs = ['lib']
-        @metrics = @available_metrics
-      end
+      set_metrics
+      set_code_dirs
       @flay     = { :dirs_to_flay => @code_dirs  } 
       @flog     = { :dirs_to_flog => @code_dirs  }
       @reek     = { :dirs_to_reek => @code_dirs  }
@@ -82,7 +138,7 @@ def reset
                     :formater => "text"}
       @churn    = {}
       @stats    = {}
-      @coverage = { :test_files => ['test/**/*_test.rb', 
+      @rcov     = { :test_files => ['test/**/*_test.rb', 
                                     'spec/**/*_spec.rb'],
                     :rcov_opts => ["--sort coverage", 
                                    "--no-html", 
@@ -93,5 +149,39 @@ def reset
                                    "--exclude /gems/,/Library/,spec"]}
     end
 
+    # Perform a simple check to try and guess if we're running
+    # against a rails app.
+    #
+    # @todo  This should probably be made a bit more robust.
+    def rails?
+      @rails = File.exist?("config/environment.rb")
+    end
+
+    # Add the :stats task to the AVAILABLE_METRICS constant if we're
+    # running within rails.
+    def set_metrics
+      if rails?
+        @metrics = MetricFu::AVAILABLE_METRICS + [:stats]
+      else
+        @metrics = MetricFu::AVAILABLE_METRICS
+      end 
+    end
+
+    # Add the 'app' directory if we're running within rails.
+    def set_code_dirs
+      if rails?
+        @code_dirs = ['app', 'lib']
+      else
+        @code_dirs = ['lib']
+      end
+    end
+
+    def platform #:nodoc:
+      return PLATFORM
+    end
+
+    def is_cruise_control_rb?
+      !!ENV['CC_BUILD_ARTIFACTS']
+    end
   end
 end