AS guide: documents Object#returning

railties/guides/source/active_support_overview.textile

@@ -84,6 +84,21 @@ By definition all objects are +duplicable?+ except +nil+, +false+, +true+, symbo
 
 WARNING. Using +duplicable?+ is discouraged because it depends on a hard-coded list. Classes have means to disallow duplication like removing +dup+ and +clone+ or raising exceptions from them, only +rescue+ can tell.
 
+h4. +returning+
+
+The method +returning+ yields its argument to a block and returns it. You tipically use it with a mutable object that gets modified in the block:
+
+<ruby>
+def html_options_for_form(url_for_options, options, *parameters_for_url)
+  returning options.stringify_keys do |html_options|
+    html_options["enctype"] = "multipart/form-data" if html_options.delete("multipart")
+    html_options["action"]  = url_for(url_for_options, *parameters_for_url)
+  end
+end
+</ruby>
+
+See also "+Object#tap+":#tap.
+
 h4. +tap+
 
 +Object#tap+ exists in Ruby 1.8.7 and 1.9, and it is defined by Active Support for previous versions. This method yields its receiver to a block and returns it.