diff --git a/lib/haml.rb b/lib/haml.rb
index 3e3a8efc..cd0d3ca8 100644
--- a/lib/haml.rb
+++ b/lib/haml.rb
@@ -530,6 +530,20 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #     <p>Hello, <em>World</em></p>
 #   </p>
 #
+# Filters can have Ruby code interpolated, like with ==.
+# For example,
+#
+#   - flavor = "raspberry"
+#   #content
+#     :textile
+#       I *really* prefer _#{h flavor}_ jam.
+#
+# is compiled to
+#
+#   <div id='content'>
+#     <p>I <strong>really</strong> prefer <em>raspberry</em> jam.</p>
+#   </div>
+#
 # Haml has the following filters defined:
 #
 # [plain]     Does not parse the filtered text.
diff --git a/lib/haml/filters.rb b/lib/haml/filters.rb
index 74349fbf..fbf7488d 100644
--- a/lib/haml/filters.rb
+++ b/lib/haml/filters.rb
@@ -1,19 +1,57 @@
 # This file contains redefinitions of and wrappers around various text
 # filters so they can be used as Haml filters.
 
-# :stopdoc:
-
-begin
-  require 'rubygems'
-rescue LoadError; end
-
 module Haml
+  # The module containing the default filters,
+  # as well as the base module,
+  # Haml::Filters::Base.
   module Filters
+    # The base module for Haml filters.
+    # User-defined filters should be modules including this module.
+    #
+    # A user-defined filter should override either Base#render or Base #compile.
+    # Base#render is the most common.
+    # It takes a string, the filter source,
+    # and returns another string,
+    # the result of the filter.
+    # For example:
+    #
+    #   module Haml::Filters::Sass
+    #     include Haml::Filters::Base
+    #
+    #     def render(text)
+    #       ::Sass::Engine.new(text).render
+    #     end
+    #   end
+    #
+    # For details on overriding #compile, see its documentation.
+    #
     module Base
-      def self.included(base)
+      def self.included(base) # :nodoc:
         base.extend(base)
       end
 
+      # Takes a string, the source text that should be passed to the filter,
+      # and returns the string resulting from running the filter on <tt>text</tt>.
+      #
+      # This should be overridden in most individual filter modules
+      # to render text with the given filter.
+      # If compile is overridden, however, render doesn't need to be.
+      def render(text)
+        raise HamlError.new("#{self.inspect}#render not defined!")
+      end
+
+      # compile should be overridden when a filter needs to have access
+      # to the Haml evaluation context.
+      # Rather than applying a filter to a string at compile-time,
+      # compile uses the Haml::Precompiler instance to compile the string to Ruby code
+      # that will be executed in the context of the active Haml template.
+      #
+      # Warning: the Haml::Precompiler interface is neither well-documented
+      # nor guaranteed to be stable.
+      # If you want to make use of it,
+      # you'll probably need to look at the source code
+      # and should test your filter when upgrading to new Haml versions.
       def compile(precompiler, text)
         resolve_lazy_requires
         filter = self
@@ -35,10 +73,28 @@ module Haml
         end
       end
 
+      # This becomes a class method of modules that include Base.
+      # It allows the module to specify one or more Ruby files
+      # that Haml should try to require when compiling the filter.
+      #
+      # The first file specified is tried first,
+      # then the second, etc.
+      # If none are found, the compilation throws an exception.
+      #
+      # For example:
+      #
+      #   module Haml::Filters::Markdown
+      #     lazy_require 'bluecloth', 'redcloth'
+      #
+      #     ...
+      #   end
+      # 
       def lazy_require(*reqs)
         @lazy_requires = reqs
       end
 
+      private
+
       def resolve_lazy_requires
         return unless @lazy_requires
 
@@ -64,7 +120,17 @@ module Haml
         end
       end
     end
+  end
+end
 
+# :stopdoc:
+
+begin
+  require 'rubygems'
+rescue LoadError; end
+
+module Haml
+  module Filters
     module Plain
       include Base