From cbd5d3d1289c40eae8b952891fd6a1c5173445fb Mon Sep 17 00:00:00 2001
From: nex3 <nex3@7063305b-7217-0410-af8c-cdc13e5119b9>
Date: Sun, 17 Dec 2006 16:45:07 +0000
Subject: [PATCH] Preliminary Sass public documentation.

git-svn-id: svn://hamptoncatlin.com/haml/trunk@230 7063305b-7217-0410-af8c-cdc13e5119b9
---
 Rakefile           |  4 ++++
 lib/haml/engine.rb |  6 +++---
 lib/sass/engine.rb | 21 +++++++++++++++++++++
 lib/sass/plugin.rb | 18 +++++++++++++++---
 4 files changed, 43 insertions(+), 6 deletions(-)

diff --git a/Rakefile b/Rakefile
index e7608da0..71945350 100644
--- a/Rakefile
+++ b/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 -----
diff --git a/lib/haml/engine.rb b/lib/haml/engine.rb
index fe02a346..9f550cc6 100644
--- a/lib/haml/engine.rb
+++ b/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>.
diff --git a/lib/sass/engine.rb b/lib/sass/engine.rb
index 57d4fab1..c8f954ae 100644
--- a/lib/sass/engine.rb
+++ b/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
diff --git a/lib/sass/plugin.rb b/lib/sass/plugin.rb
index 19bcd6d8..9ae046a4 100644
--- a/lib/sass/plugin.rb
+++ b/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]