From d7e85f363a5e8d51a6e5f5d5d98b0147343a2a1f Mon Sep 17 00:00:00 2001
From: Xavier Noria <fxn@hashref.com>
Date: Sat, 12 Sep 2009 01:58:01 +0200
Subject: documents Hash#to_xml

---
 .../active_support/core_ext/hash/conversions.rb    | 48 ++++++++++++++++++++++
 1 file changed, 48 insertions(+)

(limited to 'activesupport')

diff --git a/activesupport/lib/active_support/core_ext/hash/conversions.rb b/activesupport/lib/active_support/core_ext/hash/conversions.rb
index bd9419e1a2..aa686ec2eb 100644
--- a/activesupport/lib/active_support/core_ext/hash/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/hash/conversions.rb
@@ -83,6 +83,54 @@ class Hash
   
   alias_method :to_param, :to_query
 
+  # Returns a string containing an XML representation of its receiver:
+  # 
+  #   {"foo" => 1, "bar" => 2}.to_xml
+  #   # =>
+  #   # <?xml version="1.0" encoding="UTF-8"?>
+  #   # <hash>
+  #   #   <foo type="integer">1</foo>
+  #   #   <bar type="integer">2</bar>
+  #   # </hash>
+  # 
+  # To do so, the method loops over the pairs and builds nodes that depend on
+  # the _values_. Given a pair +key+, +value+:
+  # 
+  # * If +value+ is a hash there's a recursive call with +key+ as <tt>:root</tt>.
+  # 
+  # * If +value+ is an array there's a recursive call with +key+ as <tt>:root</tt>,
+  #   and +key+ singularized as <tt>:children</tt>.
+  # 
+  # * If +value+ is a callable object it must expect one or two arguments. Depending
+  #   on the arity, the callable is invoked with the +options+ hash as first argument
+  #   with +key+ as <tt>:root</tt>, and +key+ singularized as second argument. Its
+  #   return value becomes a new node.
+  # 
+  # * If +value+ responds to +to_xml+ the method is invoked with +key+ as <tt>:root</tt>.
+  # 
+  # * Otherwise, a node with +key+ as tag is created with a string representation of
+  #   +value+ as text node. If +value+ is +nil+ an attribute "nil" set to "true" is added.
+  #   Unless the option <tt>:skip_types</tt> exists and is true, an attribute "type" is
+  #   added as well according to the following mapping:
+  #
+  #     XML_TYPE_NAMES = {
+  #       "Symbol"     => "symbol",
+  #       "Fixnum"     => "integer",
+  #       "Bignum"     => "integer",
+  #       "BigDecimal" => "decimal",
+  #       "Float"      => "float",
+  #       "TrueClass"  => "boolean",
+  #       "FalseClass" => "boolean",
+  #       "Date"       => "date",
+  #       "DateTime"   => "datetime",
+  #       "Time"       => "datetime"
+  #     }
+  # 
+  # By default the root node is "hash", but that's configurable via the <tt>:root</tt> option.
+  # 
+  # The default XML builder is a fresh instance of <tt>Builder::XmlMarkup</tt>. You can
+  # configure your own builder with the <tt>:builder</tt> option. The method also accepts
+  # options like <tt>:dasherize</tt> and friends, they are forwarded to the builder.
   def to_xml(options = {})
     require 'builder' unless defined?(Builder)
 
-- 
cgit v1.2.3