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.

4 files changed, 50 insertions, 2 deletions

diff --git a/doc/keywords.rdoc b/doc/keywords.rdoc
index b2f72da272..a74126823d 100644
--- a/doc/keywords.rdoc
+++ b/doc/keywords.rdoc
@@ -115,7 +115,9 @@ retry::
   handling}[rdoc-ref:syntax/exceptions.rdoc]
 
 return::
-  Exits a method.  See {methods}[rdoc-ref:syntax/methods.rdoc]
+  Exits a method.  See {methods}[rdoc-ref:syntax/methods.rdoc].
+  If met in top-level scope, immediately stops interpretation of
+  the current file.
 
 self::
   The object the current method is attached to.  See
diff --git a/doc/syntax.rdoc b/doc/syntax.rdoc
index fe0f98ce4c..2463c12a63 100644
--- a/doc/syntax.rdoc
+++ b/doc/syntax.rdoc
@@ -32,3 +32,5 @@ Refinements[rdoc-ref:syntax/refinements.rdoc] ::
 Miscellaneous[rdoc-ref:syntax/miscellaneous.rdoc] ::
   +alias+, +undef+, +BEGIN+, +END+
 
+Comments[rdoc-ref:syntax/comments.rdoc] ::
+  Line and block code comments
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: