https://git.ruby-lang.org/ruby.git/commit/?id=bddb31bb37

From bddb31bb37f878cf171f89ac54f7e43d7d59c444 Mon Sep 17 00:00:00 2001
From: zverok <zverok.offline@g...>
Date: Thu, 24 Oct 2019 19:35:36 +0300
Subject: 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.

diff --git a/doc/keywords.rdoc b/doc/keywords.rdoc
index b2f72da..a741268 100644
--- a/doc/keywords.rdoc
+++ b/doc/keywords.rdoc
@@ -115,7 +115,9 @@ retry:: https://github.com/ruby/ruby/blob/trunk/doc/keywords.rdoc#L115
   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 fe0f98c..2463c12 100644
--- a/doc/syntax.rdoc
+++ b/doc/syntax.rdoc
@@ -32,3 +32,5 @@ Refinements[rdoc-ref:syntax/refinements.rdoc] :: https://github.com/ruby/ruby/blob/trunk/doc/syntax.rdoc#L32
 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 0000000..a07dd41
--- /dev/null
+++ b/doc/syntax/comments.rdoc
@@ -0,0 +1,37 @@ https://github.com/ruby/ruby/blob/trunk/doc/syntax/comments.rdoc#L1
+= 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 a2e7561..7fd58c8 100644
--- a/doc/syntax/exceptions.rdoc
+++ b/doc/syntax/exceptions.rdoc
@@ -17,7 +17,14 @@ wish to limit the scope of rescued exceptions: https://github.com/ruby/ruby/blob/trunk/doc/syntax/exceptions.rdoc#L17
     # ...
   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:
diff --git a/enumerator.c b/enumerator.c
index 18d06bb..eee3a34 100644
--- a/enumerator.c
+++ b/enumerator.c
@@ -295,7 +295,8 @@ proc_entry_ptr(VALUE proc_entry) https://github.com/ruby/ruby/blob/trunk/enumerator.c#L295
  *   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) https://github.com/ruby/ruby/blob/trunk/enumerator.c#L315
  *   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.
  *
diff --git a/proc.c b/proc.c
index 4dfcf67..1f2e311 100644
--- a/proc.c
+++ b/proc.c
@@ -3291,6 +3291,8 @@ static VALUE rb_proc_compose_to_right(VALUE self, VALUE g); https://github.com/ruby/ruby/blob/trunk/proc.c#L3291
  *     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) https://github.com/ruby/ruby/blob/trunk/proc.c#L3332
  *     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)
diff --git a/process.c b/process.c
index 00e140e..652fdaf 100644
--- a/process.c
+++ b/process.c
@@ -416,7 +416,19 @@ parent_redirect_close(int fd) https://github.com/ruby/ruby/blob/trunk/process.c#L416
 /*
  * 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) https://github.com/ruby/ruby/blob/trunk/process.c#L5139
  *  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
diff --git a/string.c b/string.c
index 7f0468f..ab585af 100644
--- a/string.c
+++ b/string.c
@@ -8374,8 +8374,8 @@ rb_str_enumerate_lines(int argc, VALUE *argv, VALUE str, VALUE ary) https://github.com/ruby/ruby/blob/trunk/string.c#L8374
 
 /*
  *  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) https://github.com/ruby/ruby/blob/trunk/string.c#L8383
  *  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) https://github.com/ruby/ruby/blob/trunk/string.c#L8428
 
 /*
  *  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"]
-- 
cgit v0.10.2


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/