Preliminary Sass public documentation.

git-svn-id: svn://hamptoncatlin.com/haml/trunk@230 7063305b-7217-0410-af8c-cdc13e5119b9

Rakefile

@@ -99,6 +99,7 @@ unless ARGV[0] == 'benchmark'
     rdoc.rdoc_files.include('REFERENCE')
     rdoc.rdoc_files.include('lib/**/*.rb')
     rdoc.rdoc_files.exclude('lib/haml/buffer.rb')
+    rdoc.rdoc_files.exclude('lib/sass/tree/*')
   end
 
   Rake::RDocTask.new do |rdoc|
@@ -111,8 +112,11 @@ unless ARGV[0] == 'benchmark'
     rdoc.rdoc_dir = 'rdoc_devel'
     rdoc.options << '--all'
     rdoc.rdoc_files.include('test/*.rb')
+    
+    # Get rid of exclusion rules
     rdoc.rdoc_files = Rake::FileList.new(*rdoc.rdoc_files.to_a)
     rdoc.rdoc_files.include('lib/haml/buffer.rb')
+    rdoc.rdoc_files.include('lib/sass/tree/*')
   end
 
   # ----- Coverage -----

lib/haml/engine.rb

@@ -3,9 +3,9 @@ require 'haml/helpers'
 require 'haml/buffer'
 
 module Haml
-  # This is the class where all the parsing and processing of the haml
+  # This is the class where all the parsing and processing of the Haml
   # template is done. It can be directly used by the user by creating a
-  # new instance and calling to_html to render the template. For example:
+  # new instance and calling <tt>to_html</tt> to render the template. For example:
   #
   #   template = File.load('templates/really_cool_template.haml')
   #   haml_engine = Haml::Engine.new(template)
@@ -202,7 +202,7 @@ module Haml
       end
     end
 
-    # Processes a single line of haml.
+    # Processes a single line of Haml.
     #
     # This method doesn't return anything; it simply processes the line and
     # adds the appropriate code to <tt>@precompiled</tt>.

lib/sass/engine.rb

@@ -4,6 +4,14 @@ require 'sass/tree/value_node'
 require 'sass/tree/rule_node'
 
 module Sass
+  # This is the class where all the parsing and processing of the Sass
+  # template is done. It can be directly used by the user by creating a
+  # new instance and calling <tt>render</tt> to render the template. For example:
+  #
+  #   template = File.load('stylesheets/sassy.sass')
+  #   sass_engine = Sass::Engine.new(template)
+  #   output = sass_engine.render
+  #   puts output
   class Engine
     # The character that begins a CSS attribute.
     ATTRIBUTE_CHAR  = ':'[0]
@@ -11,12 +19,25 @@ module Sass
     # The string that begins one-line comments.
     COMMENT_STRING  = '//'
   
+    # Creates a new instace of Sass::Engine that will compile the given
+    # template string when <tt>render</tt> is called.
+    # See REFERENCE for available options.
+    #
+    #--
+    #
+    # TODO: Add current options to REFRENCE.
+    #
+    # When adding options, remember to add information about them
+    # to REFERENCE!
+    #++
+    #
     def initialize(template, options={})
       @template = template.split("\n")
       @options = options
       @index = 0
     end
   
+    # Processes the template and returns the result as a string.
     def render
       root = Tree::Node.new
       first_line, first_tabs = next_line

lib/sass/plugin.rb

@@ -5,7 +5,9 @@ require 'rubygems'
 require 'action_controller'
 
 module Sass
-  #Rails plugin stuff. For use with ActionView.
+  # This module contains methods that ActionController calls
+  # to automatically update Sass templates that need updating.
+  # It wasn't designed to be used outside of the context of ActionController.
   module Plugin
     class << self
       @@options = {
@@ -16,7 +18,7 @@ module Sass
         :style              => :nested
       }
 
-      # Gets various options for Sass.
+      # Gets various options for Sass. See REFERENCE for details.
       #--
       # TODO: *DOCUMENT OPTIONS*
       #++
@@ -29,6 +31,11 @@ module Sass
         @@options.merge!(value)
       end
       
+      # Checks each stylesheet in <tt>options[:css_location]</tt>
+      # to see if it needs updating,
+      # and updates it using the corresponding template
+      # from <tt>options[:templates]</tt>
+      # if it does.
       def update_stylesheets
         Dir[options[:template_location] + '/*.sass'].each do |file|
           name = File.basename(file)[0...-5]
@@ -65,8 +72,13 @@ module Sass
   end
 end
 
+# This module refers to the ActionController module that's part of Ruby on Rails.
+# Sass can be used as an alternate templating engine for Rails,
+# and includes some modifications to make this more doable.
+# The documentation can be found
+# here[http://rubyonrails.org/api/classes/ActionController/Base.html].
 module ActionController
-  class Base
+  class Base # :nodoc:
     alias_method :sass_old_process, :process
     def process(*args)
       Sass::Plugin.update_stylesheets if Sass::Plugin.options[:always_update] || Sass::Plugin.options[:always_check]