From 54ef1256372a3b1f8ddc59d25792f04b6d08fbb7 Mon Sep 17 00:00:00 2001 From: Yorick Peterse Date: Fri, 4 Apr 2014 17:48:36 +0200 Subject: [PATCH] Basic docs for everything under Oga::XML. --- lib/oga/xml/cdata.rb | 7 ++++++- lib/oga/xml/comment.rb | 6 ++++++ lib/oga/xml/doctype.rb | 37 +++++++++++++++++++++++++++++++++- lib/oga/xml/document.rb | 30 ++++++++++++++++++++++++++- lib/oga/xml/element.rb | 29 ++++++++++++++++++++++++++ lib/oga/xml/node.rb | 17 ++++++++++++++-- lib/oga/xml/text.rb | 12 +++++++++++ lib/oga/xml/xml_declaration.rb | 26 +++++++++++++++++++++--- 8 files changed, 156 insertions(+), 8 deletions(-) diff --git a/lib/oga/xml/cdata.rb b/lib/oga/xml/cdata.rb index 47b1221..e76579c 100644 --- a/lib/oga/xml/cdata.rb +++ b/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 "" end diff --git a/lib/oga/xml/comment.rb b/lib/oga/xml/comment.rb index 3069883..9c79109 100644 --- a/lib/oga/xml/comment.rb +++ b/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 "" end diff --git a/lib/oga/xml/doctype.rb b/lib/oga/xml/doctype.rb index e5925bf..0e8fb02 100644 --- a/lib/oga/xml/doctype.rb +++ b/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 = "' 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 diff --git a/lib/oga/xml/document.rb b/lib/oga/xml/document.rb index 675dade..ca2e2ba 100644 --- a/lib/oga/xml/document.rb +++ b/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") diff --git a/lib/oga/xml/element.rb b/lib/oga/xml/element.rb index 34ec8f1..5437ce3 100644 --- a/lib/oga/xml/element.rb +++ b/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}" 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) } diff --git a/lib/oga/xml/node.rb b/lib/oga/xml/node.rb index a592d58..0f2cea3 100644 --- a/lib/oga/xml/node.rb +++ b/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 diff --git a/lib/oga/xml/text.rb b/lib/oga/xml/text.rb index fcfc9e8..d2e56f4 100644 --- a/lib/oga/xml/text.rb +++ b/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 diff --git a/lib/oga/xml/xml_declaration.rb b/lib/oga/xml/xml_declaration.rb index 0561eb5..a637695 100644 --- a/lib/oga/xml/xml_declaration.rb +++ b/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] :encoding The XML encoding. + # @option options [String] :version + # @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 "" end - + ## + # @param [Fixnum] indent + # @return [String] + # def inspect(indent = 0) class_name = self.class.to_s.split('::').last spacing = ' ' * indent