tomdoc'd

lib/albino/multi.rb

@@ -5,6 +5,27 @@ class Albino
     class ShellArgumentError < ArgumentError; end
   end
 
+  # Wrapper for a custom multipygmentize script.  Passes multiple code
+  # fragments in STDIN to Python.  This assumes both Python and pygments are
+  # installed.
+  #
+  # Use like so:
+  #
+  #   @syntaxer = Albino::Multi.new([ [:ruby, File.open("/some/file.rb")] ])
+  #   puts @syntaxer.colorize
+  #
+  # It takes an Array of two-element arrays [lexer, code].
+  #
+  # You can also use Albino::Multi as a drop-in replacement.  It currently has
+  # a few limitations however:
+  #
+  # * Only the HTML output format is supported.
+  # * UTF-8 encoding is forced.
+  #
+  # The default lexer is 'text'.  You need to specify a lexer yourself;
+  # because we are using STDIN there is no auto-detect.
+  #
+  # To see all lexers and formatters available, run `pygmentize -L`.
   class Multi
     include POSIX::Spawn
 
@@ -15,10 +36,25 @@ class << self
     self.timeout_threshold = 10
     self.bin = File.join(File.dirname(__FILE__), *%w(.. .. vendor multipygmentize))
 
+    # Initializes a new Albino::Multi and runs #colorize.
     def self.colorize(*args)
       new(*args).colorize
     end
 
+    # This method accepts two forms of input:
+    #
+    # DEFAULT
+    #
+    # target - The Array of two-element [lexer, code] Arrays:
+    #          lexer - The String lexer for the upcoming block of code.
+    #          code  - The String block of code to highlight.
+    #
+    # LEGACY
+    #
+    # target - The String block of code to highlight.
+    # lexer  - The String lexer for the block of code.
+    #
+    # Albino#initialize also takes format and encoding which are ignored.
     def initialize(target, lexer = :text, *args)
       @spec = case target
         when Array
@@ -29,6 +65,14 @@ def initialize(target, lexer = :text, *args)
       end
     end
 
+    # Colorizes the code blocks.
+    #
+    # options - Specify options for the child process:
+    #           timeout - A Fixnum timeout for the child process.
+    #
+    # Returns an Array of HTML highlighted code block Strings if an array of
+    # targets are given to #initialize, or just a single HTML highlighted code
+    # block String.
     def colorize(options = {})
       options[:timeout] ||= self.class.timeout_threshold
       options[:input]     = @spec.inject([]) do |memo, (lexer, code)|