add comments

README.md

@@ -27,7 +27,7 @@ model.downcase('HP AND IBM ARE TECHNOLOGY CORPORATIONS.')
 # => "HP and IBM are technology corporations."
 ```
 
-![](http://i.giphy.com/ol57TlMlftsQg.gif)
+![This gem is magic.](http://i.giphy.com/ol57TlMlftsQg.gif)
 
 IndoorVoice is based on the assumption that most acronyms contain non-word character sequences. For example, no English word has the character sequence `bm` in a word-final position, therefore `IBM` must be an acronym.
 

lib/indoor_voice.rb

@@ -43,6 +43,7 @@ def setup
       end
     end
 
+    # Determine the possible two-character sequences. Should be O(n) of all characters in all words.
     @words.each do |word|
       chars = UnicodeUtils.upcase(word, @language_id).chars
       @characters.merge(chars)
@@ -55,17 +56,20 @@ def setup
       end
     end
 
+    # Determine whether the language contains any characters requiring escaping.
     escape = @characters.intersect?(SPECIAL_CHARACTERS)
 
     patterns = {}
     types.each do |type|
       patterns[type] = []
     end
 
+    # Build the regular expressions for non-word character sequences.
     data.each do |type,hash|
       hash.each do |character,set|
         difference = @characters - set
         unless difference.empty?
+          # The first condition is just to make the patterns more human-readable.
           patterns[type] << if difference.one?
             if escape
               "#{Regexp.escape(character)}#{Regexp.escape(difference.to_a.first)}"