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.

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

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

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

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:

enumerator.c

@@ -295,7 +295,8 @@ proc_entry_ptr(VALUE proc_entry)
  *   obj.enum_for(method = :each, *args){|*args| block} -> enum
  *
  * Creates a new Enumerator which will enumerate by calling +method+ on
- * +obj+, passing +args+ if any.
+ * +obj+, passing +args+ if any. What was _yielded_ by method becomes
+ * values of enumerator.
  *
  * If a block is given, it will be used to calculate the size of
  * the enumerator without the need to iterate it (see Enumerator#size).
@@ -314,6 +315,11 @@ proc_entry_ptr(VALUE proc_entry)
  *   a = [1, 2, 3]
  *   some_method(a.to_enum)
  *
+ *   # String#split in block form is more memory-effective:
+ *   very_large_string.to_enum(:split, "|") { |chunk| return chunk if chunk.include?('DATE') }
+ *   # This could be rewritten more idiomatically with to_enum:
+ *   very_large_string.to_enum(:split, "|").lazy.grep(/DATE/).first
+ *
  * It is typical to call to_enum when defining methods for
  * a generic Enumerable, in case no block is passed.
  *

proc.c

@@ -3291,6 +3291,8 @@ static VALUE rb_proc_compose_to_right(VALUE self, VALUE g);
  *     f = proc {|x| x * x }
  *     g = proc {|x| x + x }
  *     p (f << g).call(2) #=> 16
+ *
+ *  See Proc#>> for detailed explanations.
  */
 static VALUE
 proc_compose_to_left(VALUE self, VALUE g)
@@ -3330,6 +3332,20 @@ rb_proc_compose_to_left(VALUE self, VALUE g)
  *     f = proc {|x| x * x }
  *     g = proc {|x| x + x }
  *     p (f >> g).call(2) #=> 8
+ *
+ *  <i>g</i> could be other Proc, or Method, or any other object responding to
+ *  +call+ method:
+ *
+ *     class Parser
+ *       def self.call(text)
+ *          # ...some complicated parsing logic...
+ *       end
+ *     end
+ *
+ *     pipeline = File.method(:read) >> Parser >> proc { |data| puts "data size: #{data.count}" }
+ *     pipeline.call('data.json')
+ *
+ *  See also Method#>> and Method#<<.
  */
 static VALUE
 proc_compose_to_right(VALUE self, VALUE g)

process.c

@@ -416,7 +416,19 @@ parent_redirect_close(int fd)
 /*
  * Document-module: Process
  *
- * Module to handle processes.
+ * The module contains several groups of functionality for handling OS processes:
+ *
+ * * Low-level property introspection and management of current process, like
+ *   Process.argv0, Process.pid;
+ * * Low-level introspection of other processes, like Process.getpgid, Process.getpriority;
+ * * Management of the current process: Process.abort, Process.exit, Process.daemon etc.
+ *   (for convenience, most of those are also available as a global functions,
+ *   and module functions of Kernel);
+ * * Creation and management of child processes: Process.fork, Process.spawn and
+ *   related methods;
+ * * Management of low-level system clock: Process.times and Process.clock_gettime,
+ *   which could be important for proper benchmarking and other elapsed
+ *   time measurement tasks.
  */
 
 static VALUE
@@ -5127,7 +5139,7 @@ proc_getpriority(VALUE obj, VALUE which, VALUE who)
  *  call-seq:
  *     Process.setpriority(kind, integer, priority)   -> 0
  *
- *  See Process#getpriority.
+ *  See Process.getpriority.
  *
  *     Process.setpriority(Process::PRIO_USER, 0, 19)      #=> 0
  *     Process.setpriority(Process::PRIO_PROCESS, 0, 19)   #=> 0

string.c

@@ -8374,8 +8374,8 @@ rb_str_enumerate_lines(int argc, VALUE *argv, VALUE str, VALUE ary)
 
 /*
  *  call-seq:
- *     str.each_line(separator=$/ [, getline_args]) {|substr| block } -> str
- *     str.each_line(separator=$/ [, getline_args])                   -> an_enumerator
+ *     str.each_line(separator=$/, chomp: false) {|substr| block } -> str
+ *     str.each_line(separator=$/, chomp: false)                   -> an_enumerator
  *
  *  Splits <i>str</i> using the supplied parameter as the record
  *  separator (<code>$/</code> by default), passing each substring in
@@ -8383,30 +8383,40 @@ rb_str_enumerate_lines(int argc, VALUE *argv, VALUE str, VALUE ary)
  *  supplied, the string is split into paragraphs delimited by
  *  multiple successive newlines.
  *
- *  See IO.readlines for details about getline_args.
+ *  If +chomp+ is +true+, +separator+ will be removed from the end of each
+ *  line.
  *
  *  If no block is given, an enumerator is returned instead.
  *
- *     print "Example one\n"
  *     "hello\nworld".each_line {|s| p s}
- *     print "Example two\n"
+ *     # prints:
+ *     #   "hello\n"
+ *     #   "world"
+ *
  *     "hello\nworld".each_line('l') {|s| p s}
- *     print "Example three\n"
+ *     # prints:
+ *     #   "hel"
+ *     #   "l"
+ *     #   "o\nworl"
+ *     #   "d"
+ *
  *     "hello\n\n\nworld".each_line('') {|s| p s}
+ *     # prints
+ *     #   "hello\n\n"
+ *     #   "world"
  *
- *  <em>produces:</em>
+ *     "hello\nworld".each_line(chomp: true) {|s| p s}
+ *     # prints:
+ *     #   "hello"
+ *     #   "world"
+ *
+ *     "hello\nworld".each_line('l', chomp: true) {|s| p s}
+ *     # prints:
+ *     #   "he"
+ *     #   ""
+ *     #   "o\nwor"
+ *     #   "d"
  *
- *     Example one
- *     "hello\n"
- *     "world"
- *     Example two
- *     "hel"
- *     "l"
- *     "o\nworl"
- *     "d"
- *     Example three
- *     "hello\n\n"
- *     "world"
  */
 
 static VALUE
@@ -8418,13 +8428,14 @@ rb_str_each_line(int argc, VALUE *argv, VALUE str)
 
 /*
  *  call-seq:
- *     str.lines(separator=$/ [, getline_args])  -> an_array
+ *     str.lines(separator=$/, chomp: false)  -> an_array
  *
  *  Returns an array of lines in <i>str</i> split using the supplied
  *  record separator (<code>$/</code> by default).  This is a
  *  shorthand for <code>str.each_line(separator, getline_args).to_a</code>.
  *
- *  See IO.readlines for details about getline_args.
+ *  If +chomp+ is +true+, +separator+ will be removed from the end of each
+ *  line.
  *
  *     "hello\nworld\n".lines              #=> ["hello\n", "world\n"]
  *     "hello  world".lines(' ')           #=> ["hello ", " ", "world"]