Added documentation to encoders; more code cleanups.

12 files changed, 113 insertions, 23 deletions

diff --git a/lib/coderay/encoders/count.rb b/lib/coderay/encoders/count.rb
index c9a6dfd..2e60a89 100644
--- a/lib/coderay/encoders/count.rb
+++ b/lib/coderay/encoders/count.rb
@@ -1,12 +1,15 @@
 module CodeRay
 module Encoders
-
+  
+  # Returns the number of tokens.
+  # 
+  # Text and block tokens (:open etc.) are counted.
   class Count < Encoder
 
     include Streamable
     register_for :count
 
-    protected
+  protected
 
     def setup options
       @out = 0
@@ -15,6 +18,7 @@ module Encoders
     def token text, kind
       @out += 1
     end
+    
   end
 
 end
diff --git a/lib/coderay/encoders/debug.rb b/lib/coderay/encoders/debug.rb
index 03d6876..4c680d3 100644
--- a/lib/coderay/encoders/debug.rb
+++ b/lib/coderay/encoders/debug.rb
@@ -1,3 +1,4 @@
+($:.unshift '../..'; require 'coderay') unless defined? CodeRay
 module CodeRay
 module Encoders
 
@@ -10,6 +11,8 @@ module Encoders
   # You cannot fully restore the tokens information from the
   # output, because consecutive :space tokens are merged.
   # Use Tokens#dump for caching purposes.
+  # 
+  # See also: Scanners::Debug
   class Debug < Encoder
 
     include Streamable
@@ -47,3 +50,50 @@ module Encoders
 
 end
 end
+
+if $0 == __FILE__
+  $VERBOSE = true
+  $: << File.join(File.dirname(__FILE__), '..')
+  eval DATA.read, nil, $0, __LINE__ + 4
+end
+
+__END__
+require 'test/unit'
+
+class DebugEncoderTest < Test::Unit::TestCase
+  
+  def test_creation
+    assert CodeRay::Encoders::Debug < CodeRay::Encoders::Encoder
+    debug = nil
+    assert_nothing_raised do
+      debug = CodeRay.encoder :debug
+    end
+    assert_kind_of CodeRay::Encoders::Encoder, debug
+  end
+  
+  TEST_INPUT = CodeRay::Tokens[
+    ['10', :integer],
+    ['(\\)', :operator],
+    [:open, :string],
+    ['test', :content],
+    [:close, :string],
+    [:begin_line, :test],
+    ["\n", :space],
+    ["\n  \t", :space],
+    ["   \n", :space],
+    ["[]", :method],
+    [:end_line, :test],
+  ]
+  TEST_OUTPUT = <<-'DEBUG'.chomp
+integer(10)operator((\\\))string<content(test)>test[
+
+  	   
+method([])]
+  DEBUG
+  
+  def test_filtering_text_tokens
+    assert_equal TEST_OUTPUT, CodeRay::Encoders::Debug.new.encode_tokens(TEST_INPUT)
+    assert_equal TEST_OUTPUT, TEST_INPUT.debug
+  end
+  
+end
diff --git a/lib/coderay/encoders/div.rb b/lib/coderay/encoders/div.rb
index 4120172..f9741e3 100644
--- a/lib/coderay/encoders/div.rb
+++ b/lib/coderay/encoders/div.rb
@@ -2,7 +2,10 @@ module CodeRay
 module Encoders
 
   load :html
-
+  
+  # Wraps HTML output into a DIV element, using inline styles by default.
+  # 
+  # See Encoders::HTML for available options.
   class Div < HTML
 
     FILE_EXTENSION = 'div.html'
diff --git a/lib/coderay/encoders/filter.rb b/lib/coderay/encoders/filter.rb
index 5e4b34d..c1991cf 100644
--- a/lib/coderay/encoders/filter.rb
+++ b/lib/coderay/encoders/filter.rb
@@ -2,6 +2,10 @@
 module CodeRay
 module Encoders
   
+  # A Filter encoder has another Tokens instance as output.
+  # It is used to select and delete tokens from the stream.
+  # 
+  # See also: TokenKindFilter
   class Filter < Encoder
     
     register_for :filter
diff --git a/lib/coderay/encoders/html/css.rb b/lib/coderay/encoders/html/css.rb
index 03c2634..05e4fa4 100644
--- a/lib/coderay/encoders/html/css.rb
+++ b/lib/coderay/encoders/html/css.rb
@@ -2,7 +2,7 @@ module CodeRay
 module Encoders
 
   class HTML
-    class CSS
+    class CSS  # :nodoc:
 
       attr :stylesheet
 
@@ -24,10 +24,10 @@ module Encoders
         cl = @classes[styles.first]
         return '' unless cl
         style = ''
-        1.upto(styles.size) do |offset|
+        1.upto styles.size do |offset|
           break if style = cl[styles[offset .. -1]]
         end
-        $stderr.puts 'Style not found: %p' % [styles] if $DEBUG and style.empty?
+        # warn 'Style not found: %p' % [styles] if style.empty?
         return style
       end
 
diff --git a/lib/coderay/encoders/html/output.rb b/lib/coderay/encoders/html/output.rb
index 28574a5..57d2e88 100644
--- a/lib/coderay/encoders/html/output.rb
+++ b/lib/coderay/encoders/html/output.rb
@@ -126,7 +126,7 @@ module Encoders
         Output.make_stylesheet @css, in_tag
       end
 
-      class Template < String
+      class Template < String  # :nodoc:
 
         def self.wrap! str, template, target
           target = Regexp.new(Regexp.escape("<%#{target}%>"))
@@ -147,7 +147,7 @@ module Encoders
           end
         end
 
-        module Simple
+        module Simple  # :nodoc:
           def ` str  #` <-- for stupid editors
             Template.new str
           end
diff --git a/lib/coderay/encoders/json.rb b/lib/coderay/encoders/json.rb
index 7aa077c..78f0ec0 100644
--- a/lib/coderay/encoders/json.rb
+++ b/lib/coderay/encoders/json.rb
@@ -2,7 +2,20 @@
 module CodeRay
 module Encoders
   
-  # = JSON Encoder
+  # A simple JSON Encoder.
+  # 
+  # Example:
+  #  CodeRay.scan('puts "Hello world!"', :ruby).json
+  # yields
+  #  [
+  #    {"type"=>"text", "text"=>"puts", "kind"=>"ident"},
+  #    {"type"=>"text", "text"=>" ", "kind"=>"space"},
+  #    {"type"=>"block", "action"=>"open", "kind"=>"string"},
+  #    {"type"=>"text", "text"=>"\"", "kind"=>"delimiter"},
+  #    {"type"=>"text", "text"=>"Hello world!", "kind"=>"content"},
+  #    {"type"=>"text", "text"=>"\"", "kind"=>"delimiter"},
+  #    {"type"=>"block", "action"=>"close", "kind"=>"string"},
+  #  ]
   class JSON < Encoder
     
     register_for :json
@@ -50,10 +63,7 @@ require 'rubygems' if RUBY_VERSION < '1.9'
 class JSONEncoderTest < Test::Unit::TestCase
   
   def test_json_output
-    tokens = CodeRay.scan <<-RUBY, :ruby
-puts "Hello world!"
-    RUBY
-    require 'json'
+    json = CodeRay.scan('puts "Hello world!"', :ruby).json
     assert_equal [
       {"type"=>"text", "text"=>"puts", "kind"=>"ident"},
       {"type"=>"text", "text"=>" ", "kind"=>"space"},
@@ -62,8 +72,7 @@ puts "Hello world!"
       {"type"=>"text", "text"=>"Hello world!", "kind"=>"content"},
       {"type"=>"text", "text"=>"\"", "kind"=>"delimiter"},
       {"type"=>"block", "action"=>"close", "kind"=>"string"},
-      {"type"=>"text", "text"=>"\n", "kind"=>"space"}
-    ], JSON.load(tokens.json)
+    ], JSON.load(json)
   end
   
 end
\ No newline at end of file
diff --git a/lib/coderay/encoders/null.rb b/lib/coderay/encoders/null.rb
index add3862..7a8899b 100644
--- a/lib/coderay/encoders/null.rb
+++ b/lib/coderay/encoders/null.rb
@@ -9,7 +9,7 @@ module Encoders
     include Streamable
     register_for :null
 
-    # Defined for faster processing
+    # Defined for faster processing.
     def to_proc
       proc {}
     end
diff --git a/lib/coderay/encoders/page.rb b/lib/coderay/encoders/page.rb
index 1b69cce..9f3538e 100644
--- a/lib/coderay/encoders/page.rb
+++ b/lib/coderay/encoders/page.rb
@@ -2,7 +2,11 @@ module CodeRay
 module Encoders
 
   load :html
-
+  
+  # Wraps the output into a HTML page, using CSS classes and
+  # line numbers in the table format by default.
+  # 
+  # See Encoders::HTML for available options.
   class Page < HTML
 
     FILE_EXTENSION = 'html'
diff --git a/lib/coderay/encoders/span.rb b/lib/coderay/encoders/span.rb
index 319f6fd..1596044 100644
--- a/lib/coderay/encoders/span.rb
+++ b/lib/coderay/encoders/span.rb
@@ -3,6 +3,9 @@ module Encoders
 
   load :html
 
+  # Wraps HTML output into a SPAN element, using inline styles by default.
+  # 
+  # See Encoders::HTML for available options.
   class Span < HTML
 
     FILE_EXTENSION = 'span.html'
diff --git a/lib/coderay/encoders/statistic.rb b/lib/coderay/encoders/statistic.rb
index 6d0c646..1b38938 100644
--- a/lib/coderay/encoders/statistic.rb
+++ b/lib/coderay/encoders/statistic.rb
@@ -2,16 +2,18 @@ module CodeRay
 module Encoders
 
   # Makes a statistic for the given tokens.
+  # 
+  # Alias: +stats+
   class Statistic < Encoder
 
     include Streamable
     register_for :stats, :statistic
 
-    attr_reader :type_stats, :real_token_count
+    attr_reader :type_stats, :real_token_count  # :nodoc:
 
-  protected
+    TypeStats = Struct.new :count, :size  # :nodoc:
 
-    TypeStats = Struct.new :count, :size
+  protected
 
     def setup options
       @type_stats = Hash.new { |h, k| h[k] = TypeStats.new 0, 0 }
@@ -37,7 +39,7 @@ module Encoders
       @type_stats['open/close'].count += 1
     end
 
-    STATS = <<-STATS
+    STATS = <<-STATS  # :nodoc:
 
 Code Statistics
 
@@ -51,7 +53,7 @@ Token Types (%d):
 %s
       STATS
 # space                    12007   33.81 %     1.7
-    TOKEN_TYPES_ROW = <<-TKR
+    TOKEN_TYPES_ROW = <<-TKR  # :nodoc:
   %-20s  %8d  %6.2f %%   %5.1f
       TKR
 
diff --git a/lib/coderay/encoders/text.rb b/lib/coderay/encoders/text.rb
index 161ee67..26fef84 100644
--- a/lib/coderay/encoders/text.rb
+++ b/lib/coderay/encoders/text.rb
@@ -1,6 +1,17 @@
 module CodeRay
 module Encoders
-
+  
+  # Concats the tokens into a single string, resulting in the original
+  # code string if no tokens were removed.
+  # 
+  # Alias: +plain+
+  # 
+  # == Options
+  # 
+  # === :separator
+  # A separator string to join the tokens.
+  # 
+  # Default: empty String
   class Text < Encoder
 
     include Streamable