* lib/rss/rss.rb: [DOC] Document for constants by Steve Klabnik

  [ruby-core:56705] [Bug #8798]


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

1 files changed, 23 insertions, 28 deletions

diff --git a/lib/rss/rss.rb b/lib/rss/rss.rb
index 6a942bfa63..55f7f9c805 100644
--- a/lib/rss/rss.rb
+++ b/lib/rss/rss.rb
@@ -53,14 +53,20 @@ require "rss/xml-stylesheet"
 
 module RSS
 
+  # The current version of RSS
   VERSION = "0.2.7"
 
+  # The URI of the RSS 1.0 specification
   URI = "http://purl.org/rss/1.0/"
 
-  DEBUG = false
+  DEBUG = false # :nodoc:
 
+  # The basic error all other RSS errors stem from. Rescue this error if you
+  # want to handle any given RSS error and you don't care about the details.
   class Error < StandardError; end
 
+  # RSS, being an XML-based format, has namespace support. If two namespaces are
+  # declared with the same name, an OverlappedPrefixError will be raised.
   class OverlappedPrefixError < Error
     attr_reader :prefix
     def initialize(prefix)
@@ -68,11 +74,13 @@ module RSS
     end
   end
 
+  # The InvalidRSSError error is the base class for a variety of errors
+  # related to a poorly-formed RSS feed. Rescue this error if you only
+  # care that a file could be invalid, but don't care how it is invalid.
   class InvalidRSSError < Error; end
 
-  ##
-  # Raised if no matching tag is found.
-
+  # Since RSS is based on XML, it must have opening and closing tags that
+  # match. If they don't, a MissingTagError will be raised.
   class MissingTagError < InvalidRSSError
     attr_reader :tag, :parent
     def initialize(tag, parent)
@@ -81,9 +89,9 @@ module RSS
     end
   end
 
-  ##
-  # Raised if there are more occurrences of the tag than expected.
-
+  # Some tags must only exist a specific number of times in a given RSS feed.
+  # If a feed has too many occurances of one of these tags, a TooMuchTagError
+  # will be raised.
   class TooMuchTagError < InvalidRSSError
     attr_reader :tag, :parent
     def initialize(tag, parent)
@@ -92,9 +100,8 @@ module RSS
     end
   end
 
-  ##
-  # Raised if a required attribute is missing.
-
+  # Certain attributes are required on specific tags in an RSS feed. If a feed
+  # is missing one of these attributes, a MissingAttributeError is raised.
   class MissingAttributeError < InvalidRSSError
     attr_reader :tag, :attribute
     def initialize(tag, attribute)
@@ -103,9 +110,8 @@ module RSS
     end
   end
 
-  ##
-  # Raised when an unknown tag is found.
-
+  # RSS does not allow for free-form tag names, so if an RSS feed contains a
+  # tag that we don't know about, an UnknownTagError is raised.
   class UnknownTagError < InvalidRSSError
     attr_reader :tag, :uri
     def initialize(tag, uri)
@@ -114,9 +120,7 @@ module RSS
     end
   end
 
-  ##
   # Raised when an unexpected tag is encountered.
-
   class NotExpectedTagError < InvalidRSSError
     attr_reader :tag, :uri, :parent
     def initialize(tag, uri, parent)
@@ -125,11 +129,10 @@ module RSS
     end
   end
   # For backward compatibility :X
-  NotExceptedTagError = NotExpectedTagError
-
-  ##
-  # Raised when an incorrect value is used.
+  NotExceptedTagError = NotExpectedTagError # :nodoc:
 
+  # Attributes are in key-value form, and if there's no value provided for an
+  # attribute, a NotAvailableValueError will be raised.
   class NotAvailableValueError < InvalidRSSError
     attr_reader :tag, :value, :attribute
     def initialize(tag, value, attribute=nil)
@@ -141,9 +144,7 @@ module RSS
     end
   end
 
-  ##
   # Raised when an unknown conversion error occurs.
-
   class UnknownConversionMethodError < Error
     attr_reader :to, :from
     def initialize(to, from)
@@ -153,11 +154,9 @@ module RSS
     end
   end
   # for backward compatibility
-  UnknownConvertMethod = UnknownConversionMethodError
+  UnknownConvertMethod = UnknownConversionMethodError # :nodoc:
 
-  ##
   # Raised when a conversion failure occurs.
-
   class ConversionError < Error
     attr_reader :string, :to, :from
     def initialize(string, to, from)
@@ -168,9 +167,7 @@ module RSS
     end
   end
 
-  ##
   # Raised when a required variable is not set.
-
   class NotSetError < Error
     attr_reader :name, :variables
     def initialize(name, variables)
@@ -180,9 +177,7 @@ module RSS
     end
   end
 
-  ##
   # Raised when a RSS::Maker attempts to use an unknown maker.
-
   class UnsupportedMakerVersionError < Error
     attr_reader :version
     def initialize(version)