From a40b79a01a99fa5177c6b891ce5f8cbb4a5dbb17 Mon Sep 17 00:00:00 2001
From: Joshua Peek <josh@joshpeek.com>
Date: Tue, 24 May 2011 19:38:50 -0500
Subject: [PATCH] Document Lexer

---
 lib/linguist/lexer.rb | 51 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/lib/linguist/lexer.rb b/lib/linguist/lexer.rb
index e075e0ce..8d2bdd4d 100644
--- a/lib/linguist/lexer.rb
+++ b/lib/linguist/lexer.rb
@@ -2,30 +2,75 @@ require 'albino'
 require 'yaml'
 
 module Linguist
+  # Mirror of Pygments Lexer structure.
   class Lexer < Struct.new(:name, :aliases, :filenames, :mimetypes)
     @name_index  = {}
     @alias_index = {}
 
+    # Public: Look up Lexer by its proper name.
+    #
+    # name - The case-insensitive String name of the Lexer
+    #
+    # Examples
+    #
+    #   Lexer.find_by_name('Ruby')
+    #   # => #<Lexer name="Ruby">
+    #
+    # Returns the Lexer or nil if none was found.
     def self.find_by_name(name)
       @name_index[name.downcase]
     end
 
+    # Public: Look up Lexer by one of its aliases.
+    #
+    # name - A case-sensitive String alias of the Lexer
+    #
+    # Examples
+    #
+    #   Lexer.find_by_alias('rb')
+    #   # => #<Lexer name="Ruby">
+    #
+    # Returns the Lexer or nil if none was found.
     def self.find_by_alias(name)
       @alias_index[name]
     end
 
+    # Public: Look up Lexer by name or alias.
+    #
+    # name - A case-insensitive String name or alias
+    #
+    #   Lexer['Ruby']
+    #   => #<Lexer name="Ruby">
+    #
+    # Returns the Lexer or nil if none was found.
     def self.[](name)
       find_by_name(name) || find_by_alias(name)
     end
 
+    # Public: Return a alias of the Lexer to pass to Pygments.
+    #
+    # The alias we choose is arbitrary.
+    #
+    # Returns the alias String
     def to_s
       aliases.first
     end
 
+    # Public: Highlight syntax of text
+    #
+    # text - String of code to be highlighted
+    #
+    # Returns html String
     def colorize(text)
       Albino.colorize(text, self)
     end
 
+    # Public: Highlight syntax of text without the outer highlight div
+    # wrapper.
+    #
+    # text - String of code to be highlighted
+    #
+    # Returns html String
     def colorize_without_wrapper(text)
       if text = colorize(text)
         text[%r{<div class="highlight"><pre>(.*?)</pre>\s*</div>}m, 1]
@@ -42,7 +87,12 @@ module Linguist
       equal?(other)
     end
 
+    # Load lexers from lexers.yml
+    #
+    # `bin/pygments-lexers` dumps a YAML list of all the available
+    # Pygments lexers.
     YAML.load_file(File.expand_path("../lexers.yml", __FILE__)).each do |lexer|
+      # All Lexer names should be unique. Warn if there is a duplicate.
       if @name_index.key?(lexer.name.downcase)
         warn "Duplicate lexer name: #{lexer.name}"
       end
@@ -50,6 +100,7 @@ module Linguist
       @name_index[lexer.name.downcase] = lexer
 
       lexer.aliases.each do |name|
+        # All Lexer aliases should be unique. Warn if there is a duplicate.
         if @alias_index.key?(name)
           warn "Duplicate alias: #{name}"
         end