* lib/rss/parser.rb, lib/rss/utils.rb: merge documents from ruby_1_8.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@17675 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

2 files changed, 34 insertions, 4 deletions

diff --git a/lib/rss/parser.rb b/lib/rss/parser.rb
index 2e137da3ed..8e91fb6ef6 100644
--- a/lib/rss/parser.rb
+++ b/lib/rss/parser.rb
@@ -8,6 +8,10 @@ module RSS
 
   class NotWellFormedError < Error
     attr_reader :line, :element
+
+    # Create a new NotWellFormedError for an error at +line+
+    # in +element+.  If a block is given the return value of
+    # the block ends up in the error message.
     def initialize(line=nil, element=nil)
       message = "This is not well formed XML"
       if element or line
@@ -22,15 +26,15 @@ module RSS
 
   class XMLParserNotFound < Error
     def initialize
-      super("available XML parser does not found in " <<
+      super("available XML parser was not found in " <<
             "#{AVAILABLE_PARSER_LIBRARIES.inspect}.")
     end
   end
 
   class NotValidXMLParser < Error
     def initialize(parser)
-      super("#{parser} is not available XML parser. " <<
-            "available XML parser is " <<
+      super("#{parser} is not an available XML parser. " <<
+            "Available XML parser is " <<
             "#{AVAILABLE_PARSERS.inspect}.")
     end
   end
@@ -56,6 +60,8 @@ module RSS
         @@default_parser || AVAILABLE_PARSERS.first
       end
 
+      # Set @@default_parser to new_value if it is one of the
+      # available parsers. Else raise NotValidXMLParser error.
       def default_parser=(new_value)
         if AVAILABLE_PARSERS.include?(new_value)
           @@default_parser = new_value
@@ -83,6 +89,10 @@ module RSS
     end
 
     private
+
+    # Try to get the XML associated with +rss+.
+    # Return +rss+ if it already looks like XML, or treat it as a URI,
+    # or a file to get the XML,
     def normalize_rss(rss)
       return rss if maybe_xml?(rss)
 
@@ -97,10 +107,13 @@ module RSS
       end
     end
 
+    # maybe_xml? tests if source is a string that looks like XML.
     def maybe_xml?(source)
       source.is_a?(String) and /</ =~ source
     end
 
+    # Attempt to convert rss to a URI, but just return it if
+    # there's a ::URI::Error
     def to_uri(rss)
       return rss if rss.is_a?(::URI::Generic)
 
@@ -164,6 +177,7 @@ module RSS
       @@registered_uris = {}
       @@class_names = {}
 
+      # return the setter for the uri, tag_name pair, or nil.
       def setter(uri, tag_name)
         _getter = getter(uri, tag_name)
         if _getter
@@ -177,29 +191,35 @@ module RSS
         (@@accessor_bases[uri] || {})[tag_name]
       end
 
+      # return the tag_names for setters associated with uri
       def available_tags(uri)
         (@@accessor_bases[uri] || {}).keys
       end
       
+      # register uri against this name.
       def register_uri(uri, name)
         @@registered_uris[name] ||= {}
         @@registered_uris[name][uri] = nil
       end
       
+      # test if this uri is registered against this name
       def uri_registered?(uri, name)
         @@registered_uris[name].has_key?(uri)
       end
 
+      # record class_name for the supplied uri and tag_name
       def install_class_name(uri, tag_name, class_name)
         @@class_names[uri] ||= {}
         @@class_names[uri][tag_name] = class_name
       end
 
+      # retrieve class_name for the supplied uri and tag_name
+      # If it doesn't exist, capitalize the tag_name
       def class_name(uri, tag_name)
         name = (@@class_names[uri] || {})[tag_name]
         return name if name
 
-        tag_name.gsub!(/[_\-]([a-z]?)/){$1.upcase}
+        tag_name = tag_name.gsub(/[_\-]([a-z]?)/) {$1.upcase}
         tag_name[0, 1].upcase + tag_name[1..-1]
       end
 
@@ -213,6 +233,7 @@ module RSS
       end
     
       private
+      # set the accessor for the uri, tag_name pair
       def install_accessor_base(uri, tag_name, accessor_base)
         @@accessor_bases[uri] ||= {}
         @@accessor_bases[uri][tag_name] = accessor_base.chomp("=")
@@ -258,6 +279,7 @@ module RSS
       @last_xml_element = nil
     end
     
+    # set instance vars for version, encoding, standalone
     def xmldecl(version, encoding, standalone)
       @version, @encoding, @standalone = version, encoding, standalone
     end
@@ -350,6 +372,9 @@ module RSS
     end
 
     CONTENT_PATTERN = /\s*([^=]+)=(["'])([^\2]+?)\2/
+    # Extract the first name="value" pair from content.
+    # Works with single quotes according to the constant
+    # CONTENT_PATTERN. Return a Hash.
     def parse_pi_content(content)
       params = {}
       content.scan(CONTENT_PATTERN) do |name, quote, value|
diff --git a/lib/rss/utils.rb b/lib/rss/utils.rb
index a24fc173d6..0e4001e1f3 100644
--- a/lib/rss/utils.rb
+++ b/lib/rss/utils.rb
@@ -1,6 +1,8 @@
 module RSS
   module Utils
     module_function
+
+    # Convert a name_with_underscores to CamelCase.
     def to_class_name(name)
       name.split(/[_\-]/).collect do |part|
         "#{part[0, 1].upcase}#{part[1..-1]}"
@@ -14,11 +16,14 @@ module RSS
       [file, line]
     end
 
+    # escape '&', '"', '<' and '>' for use in HTML.
     def html_escape(s)
       s.to_s.gsub(/&/, "&amp;").gsub(/\"/, "&quot;").gsub(/>/, "&gt;").gsub(/</, "&lt;")
     end
     alias h html_escape
     
+    # If +value+ is an instance of class +klass+, return it, else
+    # create a new instance of +klass+ with value +value+.
     def new_with_value_if_need(klass, value)
       if value.is_a?(klass)
         value