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.

1 files changed, 37 insertions, 0 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