normatron 0.3.1 → 0.3.2

data/.yardopts

@@ -0,0 +1,2 @@
+--protected
+--markup textile

data/lib/normatron/filters.rb

@@ -4,34 +4,52 @@ end
 
 module Normatron
 
+  ##
   # Top-Level namespace of all built-in Normatron filters.
   # 
   # All filters share some characteristics:
-  # * They have the <code>Filter</code> suffix in the name.
-  # * Has a class method called <code>evaluate</code>, which runs what the filter claims to do.
-  # * The first argument of the method <code>evaluate</code> always will be the variable to be filtered.
-  # * They returns a different object from the input variable, i.e., even if object value remains unchanged, the <code>object_id</code> will be different.
-  # * They treat unicode characters(<code>/\p{Ll}\p{Lu}/u</code>) instead of only ASCII characters(<code>/[a-zA-Z]/</code>).
-  # 
-  # table{font-family: monospace; font-size: 90%}.
-  # |_. CLASS                                     |_. SYMBOL  |_. SHORT DESCRIPTION                                                                  |
-  # |"AsciiFilter":./Filters/AsciiFilter          |:ascii     |Converts Unicode(and accented ASCII) characters to their plain-text ASCII equivalents.|
-  # |"BlankFilter":./Filters/BlankFilter          |:blank     |Returns nil for a blank string or the string itself otherwise.                        |
-  # |"CamelizeFilter":./Filters/CamelizeFilter    |:camelize  |Convert string to UpperCamelCase or lowerCamelCase.                                   |
-  # |"CapitalizeFilter":./Filters/CapitalizeFilter|:capitalize|Makes only the first character as capital letter.                                     |
-  # |"ChompFilter":./Filters/ChompFilter          |:chomp     |Remove the given record separator from the end of the string.                         |
-  # |"DasherizeFilter":./Filters/DasherizeFilter  |:dasherize |Replaces all underscores with dashes.                                                 |
-  # |"DowncaseFilter":./Filters/DowncaseFilter    |:downcase  |Lowercase all characters.                                                             |
-  # |"DumpFilter":./Filters/DumpFilter            |:dump      |Creates a literal string representation.                                              |
-  # |"KeepFilter":./Filters/KeepFilter            |:keep      |Remove the characters that doesn't match the given properties.                        |
-  # |"RemoveFilter":./Filters/RemoveFilter        |:remove    |Remove the characters that match the given properties.                                |
-  # |"SqueezeFilter":./Filters/SqueezeFilter      |:squeeze   |Remove multiple occurences of the same character.                                     |
-  # |"SquishFilter":./Filters/SquishFilter        |:squish    |Strips the input, remove line-breaks and multiple spaces.                             |
-  # |"SwapcaseFilter":./Filters/SwapcaseFilter    |:swapcase  |Replaces uppercased characters by lowercased and vice versa.                          |
-  # |"TitleizeFilter":./Filters/TitleizeFilter    |:titleize  |Capitalizes the first character of each word.                                         |
-  # |"UnderscoreFilter":./Filters/UnderscoreFilter|:underscore|Makes an underscored lowercase form from the expression in the string.                |
-  # |"UpcaseFilter":./Filters/UpcaseFilter        |:upcase    |Uppercase all characters.                                                             |
+  #
+  # * They have the _Filter_ suffix in the name.
+  # * Has a class method called @evaluate@, which runs what the filter claims to do.
+  # * The first argument of the @evaluate@ method always will be the variable to be filtered.
+  # * When filtraton is done succesfully, the @object_id@ of filtered value and input value are different.
+  # * They treat unicode characters(@/[\p{Ll}\p{Lu}]/u@) instead of only ASCII characters(@/[a-zA-Z]/@).
+  #
+  # |_<. Class                                        |_<. Symbol     |_<. Short Description                                                                   |
+  # | "@AsciiFilter@":./Filters/AsciiFilter           | @:ascii@      | Converts Unicode(and accented ASCII) characters to their plain-text ASCII equivalents. |
+  # | "@BlankFilter@":./Filters/BlankFilter           | @:blank@      | Returns nil for a blank string or the string itself otherwise.                         |
+  # | "@CamelizeFilter@":./Filters/CamelizeFilter     | @:camelize@   | Convert string to UpperCamelCase or lowerCamelCase.                                    |
+  # | "@CapitalizeFilter@":./Filters/CapitalizeFilter | @:capitalize@ | Makes only the first character as capital letter.                                      |
+  # | "@ChompFilter@":./Filters/ChompFilter           | @:chomp@      | Remove the given record separator from the end of the string.                          |
+  # | "@DasherizeFilter@":./Filters/DasherizeFilter   | @:dasherize@  | Replaces all underscores with dashes.                                                  |
+  # | "@DowncaseFilter@":./Filters/DowncaseFilter     | @:downcase@   | Lowercase all characters.                                                              |
+  # | "@DumpFilter@":./Filters/DumpFilter             | @:dump@       | Creates a literal string representation.                                               |
+  # | "@KeepFilter@":./Filters/KeepFilter             | @:keep@       | Remove the characters that doesn't match the given properties.                         |
+  # | "@RemoveFilter@":./Filters/RemoveFilter         | @:remove@     | Remove the characters that match the given properties.                                 |
+  # | "@SqueezeFilter@":./Filters/SqueezeFilter       | @:squeeze@    | Remove multiple occurences of the same character.                                      |
+  # | "@SquishFilter@":./Filters/SquishFilter         | @:squish@     | Strips the input, remove line-breaks and multiple spaces.                              |
+  # | "@SwapcaseFilter@":./Filters/SwapcaseFilter     | @:swapcase@   | Replaces uppercased characters by lowercased and vice versa.                           |
+  # | "@TitleizeFilter@":./Filters/TitleizeFilter     | @:titleize@   | Capitalizes the first character of each word.                                          |
+  # | "@UnderscoreFilter@":./Filters/UnderscoreFilter | @:underscore@ | Makes an underscored lowercase form from the expression in the string.                 |
+  # | "@UpcaseFilter@":./Filters/UpcaseFilter         | @:upcase@     | Uppercase all characters.                                                              | 
   module Filters
   end
 end
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

data/lib/normatron/filters/ascii_filter.rb

@@ -2,23 +2,29 @@ require 'stringex/unidecoder'
 
 module Normatron
   module Filters
+    
+    ##
+    # Converts Unicode(and accented ASCII) characters to their plain-text ASCII equivalents.
+    # 
+    # @example Out of box
+    #   AsciiFilter.evaluate("EVOLUÇÃO")  #=> "EVOLUCAO"
+    #   AsciiFilter.evaluate("⠋⠗⠁⠝⠉⠑")  #=> "france"
+    #
+    # @example Using as model normalizer
+    #   normalize :attribute_a, :with => :ascii
+    #   normalize :attribute_b, :with => [:custom_filter, :ascii]
+    #
+    # @see http://rubydoc.info/gems/stringex/Stringex/Unidecoder Stringex::Unidecoder
     module AsciiFilter
 
       ##
-      # Converts Unicode(and accented ASCII) characters to their plain-text ASCII equivalents.
-      # 
-      # @example
-      #   AsciiFilter.evaluate("EVOLUÇÃO")       #=> "EVOLUCAO"
-      #   AsciiFilter.evaluate("⠋⠗⠁⠝⠉⠑")      #=> "france"
+      # Performs input conversion according to filter requirements.
       #
-      # @example Using as ActiveRecord::Base normalizer
-      #   normalize :attribute_a, :with => :ascii
-      #   normalize :attribute_b, :with => [:custom_filter, :ascii]
+      # This method returns the object itself when the first argument is not a String.
       #
-      # @param [String] input A character sequence
-      # @return [String] The transliterated character sequence or the object itself
-      # @see http://rubydoc.info/gems/stringex/Stringex/Unidecoder Stringex::Unidecoder
-      def self.evaluate(input, *args)
+      # @param  input [String] The String to be filtered
+      # @return [String] A new transliterated String
+      def self.evaluate(input)
         input.kind_of?(String) ? Stringex::Unidecoder.decode(input) : input
       end
     end

data/lib/normatron/filters/blank_filter.rb

@@ -1,26 +1,30 @@
-require 'normatron/filters/helpers'
-
 module Normatron
   module Filters
+    
+    ##
+    # Returns nil for a blank string or the string itself otherwise.
+    # 
+    # @example Out of box
+    #   BlankFilter.evaluate("")            #=> nil
+    #   BlankFilter.evaluate("     ")       #=> nil
+    #   BlankFilter.evaluate("  \n ")       #=> nil
+    #   BlankFilter.evaluate("1")           #=> "1"
+    #   BlankFilter.evaluate("It's blank?") #=> "It's blank?"
+    #
+    # @example Using as model normalizer
+    #   normalize :attribute_a, :with => :blank
+    #   normalize :attribute_b, :with => [:custom_filter, :blank]
+    #
+    # @see http://api.rubyonrails.org/classes/String.html#method-i-blank-3F String#blank?
     module BlankFilter
 
       ##
-      # Returns nil for a blank string or the string itself otherwise.
-      # 
-      # @example
-      #   BlankFilter.evaluate("")            #=> nil
-      #   BlankFilter.evaluate("     ")       #=> nil
-      #   BlankFilter.evaluate("  \n ")       #=> nil
-      #   BlankFilter.evaluate("1")           #=> "1"
-      #   BlankFilter.evaluate("It's blank?") #=> "It's blank?"
+      # Performs input conversion according to filter requirements.
       #
-      # @example Using as ActiveRecord::Base normalizer
-      #   normalize :attribute_a, :with => :blank
-      #   normalize :attribute_b, :with => [:custom_filter, :blank]
+      # This method returns the object itself when the first argument is not a String.
       #
-      # @param input [String] A character sequence
+      # @param  input [String] The String to be filtered
       # @return [String, nil] The object itself or nil
-      # @see http://api.rubyonrails.org/classes/String.html#method-i-blank-3F String#blank?
       def self.evaluate(input)
         input.kind_of?(String) && input.blank? ? nil : input
       end

data/lib/normatron/filters/camelize_filter.rb

@@ -2,48 +2,53 @@ require 'normatron/filters/helpers'
 
 module Normatron
   module Filters
+    
+    ##
+    # Converts strings to UpperCamelCase by default and to lowerCamelCase if the @:lower@ argument is given.
+    #
+    # It will also convert '/' to '::' which is useful for converting paths to namespaces.
+    #
+    # As a rule of thumb you can think of camelize as the inverse of underscore, though there are cases where that does
+    # not hold:
+    #
+    # pre. "SSLError".underscore.camelize # => "SslError"
+    #
+    # This filter has a similar behavior to
+    # "ActiveSupport::Inflector#camelize (ActiveSupport camelize)":http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-camelize,
+    # but it affects UTF-8 characters too.
+    # 
+    # @example Out of box
+    #   CamelizeFilter.evaluate("active_record/errors")         #=> "ActiveRecord::Errors"
+    #   CamelizeFilter.evaluate("active_record/errors", :upper) #=> "ActiveRecord::Errors"
+    #   CamelizeFilter.evaluate("active_record/errors", :lower) #=> "activeRecord::Errors"
+    #
+    # @example Using as model normalizer
+    #   normalize :attribute_a, :with => :camelize
+    #   normalize :attribute_b, :with => [:custom_filter, :camelize]
+    #   normalize :attribute_c, :with => [[:camelize, :lower]]
+    #   normalize :attribute_d, :with => [{:camelize => :lower}]
+    #   normalize :attribute_e, :with => [:custom_filter, [:camelize, :lower]]
+    #   normalize :attribute_f, :with => [:custom_filter, {:camelize => :lower}]
+    #
+    # @see http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-camelize ActiveSupport::Inflector#camelize
+    # @see UnderscoreFilter Normatron::Filters::UnderscoreFilter
     module CamelizeFilter
       extend Helpers
 
       ##
-      # Converts strings to UpperCamelCase by default and to lowerCamelCase if the <tt>:lower</tt> argument is given.
-      # <tt>camelize</tt> will also convert '/' to '::' which is useful for converting paths to namespaces.
-      # As a rule of thumb you can think of camelize as the inverse of underscore, though there are cases where that does not hold:
-      #   "SSLError".underscore.camelize # => "SslError"
-      # This filter has a similar behavior to
-      # ActiveSupport::Inflector#camelize[http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-camelize], but with following differences:
-      # * Uses UTF-8 charset
-      # * Affects accented characters
-      # 
-      # @example
-      #   CamelizeFilter.evaluate("active_record/errors")         #=> "ActiveRecord::Errors"
-      #   CamelizeFilter.evaluate("active_record/errors", :upper) #=> "ActiveRecord::Errors"
-      #   CamelizeFilter.evaluate("active_record/errors", :lower) #=> "activeRecord::Errors"
+      # Performs input conversion according to filter requirements.
       #
-      # @example Using as ActiveRecord::Base normalizer
-      #   normalize :attribute_a, :with => :camelize
-      #   normalize :attribute_b, :with => [:custom_filter, :camelize]
-      #   normalize :attribute_c, :with => [[:camelize, :lower]]
-      #   normalize :attribute_d, :with => [{:camelize => :lower}]
-      #   normalize :attribute_e, :with => [:custom_filter, [:camelize, :lower]]
-      #   normalize :attribute_f, :with => [:custom_filter, {:camelize => :lower}]
+      # This method returns the object itself when the first argument is not a String.
       #
-      # @param [String] input A character sequence
-      # @param [Symbol] first_letter_case <tt>:lower</tt> for lowerCamelCase or <tt>:upper</tt> for UpperCamelCase
-      # @return [String] The camelized character sequence or the object itself
-      # @see http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-camelize ActiveSupport::Inflector#camelize
-      # @see UnderscoreFilter Normatron::Filters::UnderscoreFilter
-      # @todo Performance tests
-      # @todo Exception class
-      def self.evaluate(input, first_letter_case = :upper)
+      # @param  input [String] The String to be filtered
+      # @param  camel [Symbol] @:lower@ for lowerCamelCase or @:upper@ for UpperCamelCase
+      # @return [String] A new camelized String
+      def self.evaluate(input, camel = :upper)
         return input unless input.kind_of?(String)
 
-        if first_letter_case == :upper
-          string = input.sub(/^[\p{L}\d]*/u) { acronyms[$&] || mb_send(:capitalize, $&) }
-        else first_letter_case == :lower
-          string = input.sub(/^(?:#{acronym_regex}(?=\b|[\p{L}_])|\p{Word}*_)/u) { mb_send(:downcase, $&) }
-        end
-        string.gsub!(/(?:_|(\/))([\p{L}\d]*)/iu) { "#{$1}#{acronyms[$2] || mb_send(:capitalize, $2)}" }.gsub!('/', '::')
+        string = mb_send(:downcase, input)
+        string.sub!(/^[^_|\/]+/) { camel == :upper ? acronyms[$&] || mb_send(:capitalize, $&) : $& }
+        string.gsub(/(?:(\/)|_)([^\/|_]+)/) { "#{$1}#{acronyms[$2] || mb_send(:capitalize, $2)}" }.gsub("/", "::")
       end
     end
   end

data/lib/normatron/filters/capitalize_filter.rb

@@ -2,25 +2,31 @@ require 'normatron/filters/helpers'
 
 module Normatron
   module Filters
+    
+    ##
+    # Makes the first character uppercase and all remaining characters lowercase.
+    # 
+    # @example Out of box
+    #   CapitalizeFilter.evaluate("KEEP IT SIMPLE")  #=> "Keep it simple"
+    #   CapitalizeFilter.evaluate("keep it simple")  #=> "Keep it simple"
+    #   CapitalizeFilter.evaluate(" KEEP IT SIMPLE") #=> " keep it simple"
+    #
+    # @example Using as model normalizer
+    #   normalize :attribute_a, :with => :capitalize
+    #   normalize :attribute_b, :with => [:custom_filter, :capitalize]
+    #
+    # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-capitalize String#capitalize
+    # @see TitleizeFilter Normatron::Filters::TitleizeFilter
     module CapitalizeFilter
       extend Helpers
 
       ##
-      # Makes the first character uppercase after lowercase all other characters.
-      # 
-      # @example
-      #   CapitalizeFilter.evaluate("KEEP IT SIMPLE")  #=> "Keep it simple"
-      #   CapitalizeFilter.evaluate("keep it simple")  #=> "Keep it simple"
-      #   CapitalizeFilter.evaluate(" KEEP IT SIMPLE") #=> " keep it simple"
+      # Performs input conversion according to filter requirements.
       #
-      # @example Using as ActiveRecord::Base normalizer
-      #   normalize :attribute_a, :with => :capitalize
-      #   normalize :attribute_b, :with => [:custom_filter, :capitalize]
+      # This method returns the object itself when the first argument is not a String.
       #
-      # @param [String] input A character sequence
-      # @return [String] The capitalized character sequence or the object itself
-      # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-capitalize String#capitalize
-      # @see TitleizeFilter Normatron::Filters::TitleizeFilter
+      # @param  input [String] The String to be filtered
+      # @return [String] A new capitalized String
       def self.evaluate(input)
         input.kind_of?(String) ? mb_send(:capitalize, input) : input
       end

data/lib/normatron/filters/chomp_filter.rb

@@ -1,31 +1,37 @@
 module Normatron
   module Filters
+    
+    ##
+    # Remove the given record separator from the end of the string (If present).
+    # If @$/@ has not been changed from the default Ruby record separator, then chomp also removes carriage return
+    # characters (that is it will remove @\n@, @\r@, and @\r\n@).
+    # 
+    # @example Out of box
+    #   ChompFilter.evaluate("Bon Scott\n")         #=> "Bon Scott"
+    #   ChompFilter.evaluate("Bon Scott\r")         #=> "Bon Scott"
+    #   ChompFilter.evaluate("Bon Scott\r\n")       #=> "Bon Scott"
+    #   ChompFilter.evaluate("Bon Scott\n\r")       #=> "Bon Scott\n"
+    #   ChompFilter.evaluate("Bon Scott", " Scott") #=> "Bon"
+    #
+    # @example Using as model normalizer
+    #   normalize :attribute_a, :with => :chomp
+    #   normalize :attribute_b, :with => [:custom_filter, :chomp]
+    #   normalize :attribute_c, :with => [[:chomp, "x"]]
+    #   normalize :attribute_d, :with => [{:chomp => "y"}]
+    #   normalize :attribute_e, :with => [:custom_filter, [:chomp, "z"]]
+    #   normalize :attribute_f, :with => [:custom_filter, {:chomp => "\f"}]
+    #
+    # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-chomp String#chomp
     module ChompFilter
 
       ##
-      # Remove the given record separator from the end of the string (If present).
-      # If <tt>$/</tt> has not been changed from the default Ruby record separator,
-      # then chomp also removes carriage return characters (that is it will remove <tt>\n</tt>, <tt>\r</tt>, and <tt>\r\n</tt>).
-      # 
-      # @example
-      #   ChompFilter.evaluate("Bon Scott\n")            #=> "Bon Scott"
-      #   ChompFilter.evaluate("Bon Scott\r")            #=> "Bon Scott"
-      #   ChompFilter.evaluate("Bon Scott\r\n")          #=> "Bon Scott"
-      #   ChompFilter.evaluate("Bon Scott\n\r")          #=> "Bon Scott\n"
-      #   ChompFilter.evaluate("Bon Scott", " Scott")    #=> "Bon"
+      # Performs input conversion according to filter requirements.
       #
-      # @example Using as ActiveRecord::Base normalizer
-      #   normalize :attribute_a, :with => :chomp
-      #   normalize :attribute_b, :with => [:custom_filter, :chomp]
-      #   normalize :attribute_c, :with => [[:chomp, "x"]]
-      #   normalize :attribute_d, :with => [{:chomp => "y"}]
-      #   normalize :attribute_e, :with => [:custom_filter, [:chomp, "z"]]
-      #   normalize :attribute_f, :with => [:custom_filter, {:chomp => "\f"}]
+      # This method returns the object itself when the first argument is not a String.
       #
-      # @param [String] input A character sequence
-      # @param [String] separator A character sequence
-      # @return [String] The chopped character sequence or the object itself
-      # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-chomp String#chomp
+      # @param  input     [String] The String to be filtered
+      # @param  separator [String] The separator used to chomp input
+      # @return [String] A new chopped String
       def self.evaluate(input, separator=$/)
         input.kind_of?(String) ? input.chomp(separator) : input
       end

data/lib/normatron/filters/dasherize_filter.rb

@@ -2,21 +2,27 @@ require 'normatron/filters/helpers'
 
 module Normatron
   module Filters
+    
+    ##
+    # Replaces all underscores with dashes.
+    # 
+    # @example Out of box
+    #   DasherizeFilter.evaluate("monty_python") #=> "monty-python"
+    #
+    # @example Using as model normalizer
+    #   normalize :attribute_a, :with => :dasherize
+    #   normalize :attribute_b, :with => [:custom_filter, :dasherize]
+    #
+    # @see http://api.rubyonrails.org/classes/String.html#method-i-dasherize String#dasherize
     module DasherizeFilter
 
       ##
-      # Replaces all underscores with dashes.
-      # 
-      # @example
-      #   DasherizeFilter.evaluate("monty_python") #=> "monty-python"
+      # Performs input conversion according to filter requirements.
       #
-      # @example Using as ActiveRecord::Base normalizer
-      #   normalize :attribute_a, :with => :dasherize
-      #   normalize :attribute_b, :with => [:custom_filter, :dasherize]
+      # This method returns the object itself when the first argument is not a String.
       #
-      # @param [String] input A character sequence
-      # @return [String] The dasherized character sequence or the object itself
-      # @see http://api.rubyonrails.org/classes/String.html#method-i-dasherize String#dasherize
+      # @param  input [String] The String to be filtered
+      # @return [String] A new dasherized String
       def self.evaluate(input)
         input.kind_of?(String) ? input.dasherize : input
       end

data/lib/normatron/filters/downcase_filter.rb

@@ -2,25 +2,31 @@ require 'normatron/filters/helpers'
 
 module Normatron
   module Filters
+    
+    ##
+    # Lowercase all characters.
+    # 
+    # @example Out of box
+    #   DowncaseFilter.evaluate("NOTHING ELSE MATTERS") #=> "nothing else matters"
+    #
+    # @example Using as ActiveRecord::Base normalizer
+    #   normalize :attribute_a, :with => :downcase
+    #   normalize :attribute_b, :with => [:custom_filter, :downcase]
+    #
+    # @see http://api.rubyonrails.org/classes/ActiveSupport/Multibyte/Chars.html#method-i-downcase ActiveSupport::Multibyte::Chars#downcase
+    # @see SwapcaseFilter Normatron::Filters::SwapcaseFilter
+    # @see TitleizeFilter Normatron::Filters::TitleizeFilter
+    # @see UpcaseFilter   Normatron::Filters::UpcaseFilter
     module DowncaseFilter
       extend Helpers
 
       ##
-      # Lowercase all characters.
-      # 
-      # @example
-      #   DowncaseFilter.evaluate("NOTHING ELSE MATTERS") #=> "nothing else matters"
+      # Performs input conversion according to filter requirements.
       #
-      # @example Using as ActiveRecord::Base normalizer
-      #   normalize :attribute_a, :with => :downcase
-      #   normalize :attribute_b, :with => [:custom_filter, :downcase]
+      # This method returns the object itself when the first argument is not a String.
       #
-      # @param [String] input A character sequence
-      # @return [String] The lowercased character sequence or the object itself
-      # @see http://api.rubyonrails.org/classes/ActiveSupport/Multibyte/Chars.html#method-i-downcase ActiveSupport::Multibyte::Chars#downcase
-      # @see SwapcaseFilter Normatron::Filters::SwapcaseFilter
-      # @see TitleizeFilter Normatron::Filters::TitleizeFilter
-      # @see UpcaseFilter Normatron::Filters::UpcaseFilter
+      # @param input [String] The String to be filtered
+      # @return [String] A new lowercased String
       def self.evaluate(input)
         input.kind_of?(String) ? mb_send(:downcase, input) : input
       end

data/lib/normatron/filters/dump_filter.rb

@@ -1,24 +1,30 @@
 module Normatron
   module Filters
+    
+    ##
+    # Creates a literal string representation with all nonprinting characters replaced by @\\n@ notation and all
+    # special characters escaped.
+    # 
+    # @example Out of box
+    #   DumpFilter.evaluate("I'm not\na \"clubber\"...") #=> "\"I'm not\\na \\\"clubber\\\"...\""
+    #   DumpFilter.evaluate("I'm not\na \"clubber\"...") #== '"I\'m not\na \"clubber\"..."'
+    #   DumpFilter.evaluate('I\'m not\na "clubber"...')  #=> "\"I'm not\\\\na \\\"clubber\\\"...\""
+    #   DumpFilter.evaluate('I\'m not\na "clubber"...')  #== '"I\'m not\\\na \"clubber\"..."'
+    #
+    # @example Using as ActiveRecord::Base normalizer
+    #   normalize :attribute_a, :with => :dump
+    #   normalize :attribute_b, :with => [:custom_filter, :dump]
+    #
+    # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-dump String#dump
     module DumpFilter
 
       ##
-      # Creates a literal string representation with all nonprinting characters
-      # replaced by <tt>\\n</tt> notation and all special characters escaped.
-      # 
-      # @example
-      #   DumpFilter.evaluate("I'm not\na \"clubber\"...") #=> "\"I'm not\\na \\\"clubber\\\"...\""
-      #   DumpFilter.evaluate("I'm not\na \"clubber\"...") #== '"I\'m not\na \"clubber\"..."'
-      #   DumpFilter.evaluate('I\'m not\na "clubber"...')  #=> "\"I'm not\\\\na \\\"clubber\\\"...\""
-      #   DumpFilter.evaluate('I\'m not\na "clubber"...')  #== '"I\'m not\\\na \"clubber\"..."'
+      # Performs input conversion according to filter requirements.
       #
-      # @example Using as ActiveRecord::Base normalizer
-      #   normalize :attribute_a, :with => :dump
-      #   normalize :attribute_b, :with => [:custom_filter, :dump]
+      # This method returns the object itself when the first argument is not a String.
       #
-      # @param [String] input A character sequence
-      # @return [String] The dumpped character sequence or the object itself
-      # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-dump String#dump
+      # @param input [String] The String to be filtered
+      # @return [String] A new dumpped String
       def self.evaluate(input)
         input.kind_of?(String) ? input.dump : input
       end