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, 16 insertions, 0 deletions

diff --git a/proc.c b/proc.c
index 4dfcf67764..1f2e31184a 100644
--- a/proc.c
+++ b/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)