Documentation improvements for Ruby core

* Top-level `return`;
* Documentation for comments syntax;
* `rescue` inside blocks;
* Enhance `Object#to_enum` docs;
* Make `chomp:` option more obvious for `String#each_line` and
  `#lines`;
* Enhance `Proc#>>` and `#<<` docs;
* Enhance `Processs` class docs.

2 files changed, 45 insertions, 1 deletions

diff --git a/doc/syntax/comments.rdoc b/doc/syntax/comments.rdoc
new file mode 100644
index 0000000000..a07dd41494
--- /dev/null
+++ b/doc/syntax/comments.rdoc
@@ -0,0 +1,37 @@
+= Code Comments
+
+Ruby has two types of comments: inline and block.
+
+Inline comments start with the <code>#</code> character and continue until the
+end of the line:
+
+  # On a separate line
+  class Foo # or at the end of the line
+    # can be indented
+    def bar
+    end
+  end
+
+Block comments start with <code>=begin</code> and end with <code>=end</code>.
+Each should start on a separate line.
+
+  =begin
+  This is
+  commented out
+  =end
+
+  class Foo
+  end
+
+  =begin some_tag
+  this works, too
+  =end
+
+<code>=begin</code> and <code>=end</code> can not be indented, so this is a
+syntax error:
+
+  class Foo
+    =begin
+    Will not work
+    =end
+  end
diff --git a/doc/syntax/exceptions.rdoc b/doc/syntax/exceptions.rdoc
index a2e75616fb..7fd58c83e8 100644
--- a/doc/syntax/exceptions.rdoc
+++ b/doc/syntax/exceptions.rdoc
@@ -17,7 +17,14 @@ wish to limit the scope of rescued exceptions:
     # ...
   end
 
-The same is true for a +class+ or +module+.
+The same is true for, +class+, +module+, and +block+:
+
+  [0, 1, 2].map do |i|
+    10 / i
+  rescue ZeroDivisionError
+    nil
+  end
+  #=> [nil, 10, 5]
 
 You can assign the exception to a local variable by using <tt>=>
 variable_name</tt> at the end of the +rescue+ line: