Basic docs for everything under Oga::XML.

lib/oga/xml/cdata.rb

@@ -1,9 +1,14 @@
 module Oga
   module XML
     ##
-    #
+    # Class used for storing information about CDATA tags.
     #
     class Cdata < Text
+      ##
+      # Converts the node back to XML.
+      #
+      # @return [String]
+      #
       def to_xml
         return "<![CDATA[#{text}]]>"
       end

lib/oga/xml/comment.rb

@@ -1,8 +1,14 @@
 module Oga
   module XML
     ##
+    # Class used for storing information about XML comments.
     #
     class Comment < Text
+      ##
+      # Converts the node back to XML.
+      #
+      # @return [String]
+      #
       def to_xml
         return "<!--#{text}-->"
       end

lib/oga/xml/doctype.rb

@@ -1,20 +1,49 @@
 module Oga
   module XML
     ##
-    # Class description
+    # Class used for storing information about Doctypes.
+    #
+    # @!attribute [rw] name
+    #  The name of the doctype (e.g. "HTML").
+    #  @return [String]
+    #
+    # @!attribute [rw] type
+    #  The type of the doctype (e.g. "PUBLIC").
+    #  @return [String]
+    #
+    # @!attribute [rw] public_id
+    #  The public ID of the doctype.
+    #  @return [String]
+    #
+    # @!attribute [rw] system_id
+    #  The system ID of the doctype.
+    #  @return [String]
     #
     class Doctype
       attr_accessor :name, :type, :public_id, :system_id
 
       ##
+      # @example
+      #  dtd = Doctype.new(:name => 'html', :type => 'PUBLIC')
+      #
       # @param [Hash] options
       #
+      # @option options [String] :name
+      # @option options [String] :type
+      # @option options [String] :public_id
+      # @option options [String] :system_id
+      #
       def initialize(options = {})
         options.each do |key, value|
           instance_variable_set("@#{key}", value) if respond_to?(key)
         end
       end
 
+      ##
+      # Converts the doctype back to XML.
+      #
+      # @return [String]
+      #
       def to_xml
         segments = "<!DOCTYPE #{name}"
 
@@ -25,6 +54,12 @@ module Oga
         return segments + '>'
       end
 
+      ##
+      # Inspects the doctype.
+      #
+      # @param [Fixnum] indent The indentation level for each line.
+      # @return [String]
+      #
       def inspect(indent = 0)
         class_name = self.class.to_s.split('::').last
         spacing    = ' ' * indent

lib/oga/xml/document.rb

@@ -1,7 +1,20 @@
 module Oga
   module XML
     ##
-    # Class description
+    # Class used for storing information about an entire XML document. This
+    # includes the doctype, XML declaration, child nodes and more.
+    #
+    # @!attribute [rw] children
+    #  The child nodes of the document.
+    #  @return [Array]
+    #
+    # @!attribute [rw] doctype
+    #  The doctype of the document.
+    #  @return [Oga::XML::Doctype]
+    #
+    # @!attribute [rw] xml_declaration
+    #  The XML declaration of the document.
+    #  @return [Oga::XML::XmlDeclaration]
     #
     class Document
       attr_accessor :children, :doctype, :xml_declaration
@@ -9,6 +22,10 @@ module Oga
       ##
       # @param [Hash] options
       #
+      # @option options [Array] :children
+      # @option options [Oga::XML::Doctype] :doctype
+      # @option options [Oga::XML::XmlDeclaration] :xml_declaration
+      #
       def initialize(options = {})
         options.each do |key, value|
           instance_variable_set("@#{key}", value) if respond_to?(key)
@@ -17,6 +34,11 @@ module Oga
         @children ||= []
       end
 
+      ##
+      # Converts the document and its child nodes to XML.
+      #
+      # @return [String]
+      #
       def to_xml
         xml = children.map(&:to_xml).join('')
 
@@ -31,6 +53,12 @@ module Oga
         return xml
       end
 
+      ##
+      # Inspects the document and its child nodes. Child nodes are indented for
+      # each nesting level.
+      #
+      # @return [String]
+      #
       def inspect
         class_name  = self.class.to_s.split('::').last
         child_lines = children.map { |child| child.inspect(4) }.join("\n")

lib/oga/xml/element.rb

@@ -4,6 +4,18 @@ module Oga
     # Class that contains information about an XML element such as the name,
     # attributes and child nodes.
     #
+    # @!attribute [rw] name
+    #  The name of the element.
+    #  @return [String]
+    #
+    # @!attribute [rw] namespace
+    #  The namespace of the element, if any.
+    #  @return [String]
+    #
+    # @!attribute [rw] attributes
+    #  The attributes of the element.
+    #  @return [Hash]
+    #
     class Element < Node
       attr_accessor :name, :namespace, :attributes
 
@@ -11,12 +23,23 @@ module Oga
         @attributes ||= {}
       end
 
+      ##
+      # Returns the value of the specified attribute.
+      #
+      # @param [String] name
+      # @return [String]
+      #
       def attribute(name)
         return attributes[name]
       end
 
       alias_method :attr, :attribute
 
+      ##
+      # Converts the element and its child elements to XML.
+      #
+      # @return [String]
+      #
       def to_xml
         ns    = namespace ? "#{namespace}:" : ''
         body  = children.map(&:to_xml).join('')
@@ -31,6 +54,12 @@ module Oga
         return "<#{ns}#{name}#{attrs}>#{body}</#{name}>"
       end
 
+      ##
+      # Returns extra data to use when calling {#inspect} on an element.
+      #
+      # @param [Fixnum] indent
+      # @return [String]
+      #
       def extra_inspect_data(indent)
         spacing     = ' ' * indent
         child_lines = children.map { |child| child.inspect(indent + 4) }

lib/oga/xml/node.rb

@@ -1,6 +1,9 @@
 module Oga
   module XML
     ##
+    # A single, generic XML node that can have a parent, next, previous and
+    # child nodes.
+    #
     # @!attribute [rw] parent
     #  @return [Oga::XML::Node]
     #
@@ -36,6 +39,14 @@ module Oga
         after_initialize if respond_to?(:after_initialize)
       end
 
+      ##
+      # Generates the inspect value for the current node. Sub classes can
+      # overwrite the {#extra_inspect_data} method to customize the output
+      # format.
+      #
+      # @param [Fixnum] indent
+      # @return [String]
+      #
       def inspect(indent = 0)
         class_name = self.class.to_s.split('::').last
         spacing    = ' ' * indent
@@ -43,8 +54,10 @@ module Oga
         return "#{spacing}#{class_name}(#{extra_inspect_data(indent)})"
       end
 
-      def extra_inspect_data
+      ##
-      end
+      # @return [String]
+      #
+      def extra_inspect_data; end
     end # Element
   end # XML
 end # Oga

lib/oga/xml/text.rb

@@ -1,14 +1,26 @@
 module Oga
   module XML
     ##
+    # Class containing information about a single text node. Text nodes don't
+    # have any children, attributes and the likes; just text.
+    #
+    # @!attribute [rw] text
+    #  @return [String]
     #
     class Text < Node
       attr_accessor :text
 
+      ##
+      # @return [String]
+      #
       def to_xml
         return text.to_s
       end
 
+      ##
+      # @param [Fixnum] indent
+      # @return [String]
+      #
       def extra_inspect_data(indent)
         return "text: #{text.inspect}"
       end

lib/oga/xml/xml_declaration.rb

@@ -1,7 +1,19 @@
 module Oga
   module XML
     ##
+    # Class containing information about an XML declaration tag.
     #
+    # @!attribute [rw] version
+    #  The XML version.
+    #  @return [String]
+    #
+    # @!attribute [rw] encoding
+    #  The XML document's encoding.
+    #  @return [String]
+    #
+    # @!attribute [rw] standalone
+    #  Whether or not the document is a standalone document.
+    #  @return [String]
     #
     class XmlDeclaration
       attr_accessor :version, :encoding, :standalone
@@ -9,8 +21,8 @@ module Oga
       ##
       # @param [Hash] options
       #
-      # @option options [String] :version The XML version.
+      # @option options [String] :version
-      # @option options [String] :encoding The XML encoding.
+      # @option options [String] :encoding
       # @option options [String] :standalone
       #
       def initialize(options = {})
@@ -22,6 +34,11 @@ module Oga
         @encoding ||= 'UTF-8'
       end
 
+      ##
+      # Converts the declaration tag to XML.
+      #
+      # @return [String]
+      #
       def to_xml
         pairs = []
 
@@ -34,7 +51,10 @@ module Oga
         return "<?xml #{pairs.join(' ')} ?>"
       end
 
-
+      ##
+      # @param [Fixnum] indent
+      # @return [String]
+      #
       def inspect(indent = 0)
         class_name = self.class.to_s.split('::').last
         spacing    = ' ' * indent