Add rdoc call-seq comments to Schema and Error classes

Author: cfis

lib/libxml/error.rb

@@ -23,7 +23,7 @@ class Error
           map[const_get(code)] = code
         end
       end
-      
+
       # Verbose error handler
       VERBOSE_HANDLER = lambda do |error|
         STDERR << error.to_s << "\n"
@@ -33,11 +33,20 @@ class Error
       # Quiet error handler
       QUIET_HANDLER = lambda do |error|
       end
-      
+
+      # call-seq:
+      #   error == other -> true or false
+      #
+      # Returns whether two errors have the same attributes.
       def ==(other)
         eql?(other)
       end
-      
+
+      # call-seq:
+      #   error.eql?(other) -> true or false
+      #
+      # Returns whether two errors have identical code, domain, message,
+      # level, file, line, and all other attributes.
       def eql?(other)
         self.code == other.code and
         self.domain == other.domain and
@@ -56,6 +65,11 @@ def eql?(other)
         false
       end
 
+      # call-seq:
+      #   error.level_to_s -> String
+      #
+      # Returns a human-readable string for the error level:
+      # "Warning:", "Error:", "Fatal error:", or "".
       def level_to_s
         case self.level
           when NONE
@@ -69,14 +83,27 @@ def level_to_s
         end
       end
 
+      # call-seq:
+      #   error.domain_to_s -> String
+      #
+      # Returns the name of the error domain (e.g. "PARSER", "XPATH").
       def domain_to_s
         DOMAIN_CODE_MAP[self.domain].to_s
       end
 
+      # call-seq:
+      #   error.code_to_s -> String
+      #
+      # Returns the name of the error code constant.
       def code_to_s
         ERROR_CODE_MAP[self.code].to_s
       end
 
+      # call-seq:
+      #   error.to_s -> String
+      #
+      # Returns a formatted error string including the level, message,
+      # and file/line when available.
       def to_s
         msg = super
         msg = msg ? msg.strip: ''

lib/libxml/schema/attribute.rb

@@ -6,10 +6,18 @@ class Schema::Attribute
       REQUIRED = 1
       OPTIONAL = 2
 
+      # call-seq:
+      #   attribute.default -> String or nil
+      #
+      # Returns the default value for this attribute, or nil if none.
       def default
         node['default']
       end
 
+      # call-seq:
+      #   attribute.required? -> true or false
+      #
+      # Returns whether this attribute is required.
       def required?
         occurs == REQUIRED
       end

lib/libxml/schema/element.rb

@@ -3,22 +3,42 @@
 module LibXML
   module XML
     class Schema::Element
+      # call-seq:
+      #   element.min_occurs -> Integer
+      #
+      # Returns the minimum number of times this element must appear.
       def min_occurs
         @min
       end
 
+      # call-seq:
+      #   element.max_occurs -> Integer
+      #
+      # Returns the maximum number of times this element may appear.
       def max_occurs
         @max
       end
 
+      # call-seq:
+      #   element.required? -> true or false
+      #
+      # Returns whether this element is required (min_occurs > 0).
       def required?
         !min_occurs.zero?
       end
 
+      # call-seq:
+      #   element.array? -> true or false
+      #
+      # Returns whether this element can appear more than once (max_occurs > 1).
       def array?
         max_occurs > 1
       end
 
+      # call-seq:
+      #   element.elements -> Hash
+      #
+      # Returns the child elements of this element's type.
       def elements
         type.elements
       end

lib/libxml/schema/type.rb

@@ -1,14 +1,37 @@
 module LibXML
   module XML
     class Schema::Type
+      # call-seq:
+      #   type.kind_name -> String
+      #
+      # Returns the name of the constant that matches this type's +kind+ value.
+      #
+      #   schema.types['shiporderType'].kind_name
+      #   # => :XML_SCHEMA_TYPE_COMPLEX
       def kind_name
         Schema::Types.constants.find { |k| Schema::Types.const_get(k) == kind }
       end
 
+      # call-seq:
+      #   type.anonymous_subtypes -> Hash
+      #
+      # Returns a Hash of child elements whose types are anonymous
+      # (inline complex types with no global name).
+      #
+      #   type.anonymous_subtypes
+      #   # => {"shipto" => #<Schema::Element>, "item" => #<Schema::Element>}
       def anonymous_subtypes
         elements.select { |_, e| e.type.name.nil? }
       end
 
+      # call-seq:
+      #   type.anonymous_subtypes_recursively -> Array
+      #
+      # Returns a flattened Array of Hashes mapping qualified names to
+      # anonymous Schema::Type instances, descending into nested types.
+      #
+      #   type.anonymous_subtypes_recursively
+      #   # => [{"shipto" => #<Schema::Type>}, {"item" => #<Schema::Type>}]
       def anonymous_subtypes_recursively(parent=nil)
         anonymous_subtypes.map do |element_name, e|
           [{[parent, element_name].compact.join('::') => e.type},