[DOC] Restore glob documentation lost in consolidation

Dir.glob's block form, Dir[]'s multiple pattern arguments, matching
only directories by a trailing slash, and the note that '**' without
a following slash is equivalent to '*' were dropped when the glob
documentation was consolidated into doc/file/filename_globbing.md
(rubyGH-17265). Restore them, with examples verified against the current
source tree.

Author: hsbt

dir.rb

@@ -213,18 +213,29 @@ def initialize(name, encoding: nil)
   end
 
   # call-seq:
-  #   Dir[patterns, base: nil, sort: true] -> array
+  #   Dir[*patterns, base: nil, sort: true] -> array
+  #
+  # Like Dir.glob, but does not accept keyword argument +flags+,
+  # and may take multiple patterns as arguments:
+  #
+  #   Dir['*.rb', '*.h'].take(3) # => ["KNOWNBUGS.rb", "array.rb", "ast.rb"]
   #
-  # Like Dir.glob, but does not accept keyword argument +flags+.
   def self.[](*args, base: nil, sort: true)
     Primitive.dir_s_aref(args, base, sort)
   end
 
   # call-seq:
   #   Dir.glob(patterns, flags: 0, base: '.', sort: true) -> array_of_entries
+  #   Dir.glob(patterns, flags: 0, base: '.', sort: true) {|entry_name| ... } -> nil
   #
   # Returns an array of filesystem entries;
   # see {Filename Globbing}[rdoc-ref:file/filename_globbing.md].
+  #
+  # With a block given, calls the block with each of the selected entry names
+  # and returns +nil+:
+  #
+  #   Dir.glob('*.rb') {|entry_name| puts entry_name } # => nil
+  #
   def self.glob(pattern, _flags = 0, flags: _flags, base: nil, sort: true)
     Primitive.attr! :use_block
     Primitive.dir_s_glob(pattern, flags, base, sort)

doc/file/filename_globbing.md

@@ -33,7 +33,10 @@ Inputs to the filename-globbing methods:
 
 Their return values:
 
-- Each of the methods `Dir[]` and Dir.glob returns an array of the selected string entries.
+- \Method `Dir[]` returns an array of the selected string entries.
+- \Method Dir.glob with no block returns an array of the selected string entries.
+- \Method Dir.glob with a block calls the block with each selected string entry
+  and returns `nil`.
 - \Method Pathname#glob with no block returns an array of Pathname objects
   each based on a selected string entry.
 - \Method Pathname#glob with a block calls the block with each pathname
@@ -44,8 +47,13 @@ Examples:
 ```ruby
 Dir['*'].take(3)
 # => ["BSDL", "CONTRIBUTING.md", "COPYING"]
+Dir['*.rb', '*.h'].take(3)
+# => ["KNOWNBUGS.rb", "array.rb", "ast.rb"]
 Dir.glob('*').take(3)
 # => ["BSDL", "CONTRIBUTING.md", "COPYING"]
+Dir.glob(['*.rb', '*.h']).take(3)
+# => ["KNOWNBUGS.rb", "array.rb", "ast.rb"]
+Dir.glob('*.rb') {|entry_name| puts entry_name } # => nil
 Pathname('.').glob('*').take(3)
 # => [#<Pathname:BSDL>, #<Pathname:CONTRIBUTING.md>, #<Pathname:COPYING>]
 a = []
@@ -299,6 +307,25 @@ Pathname('.').glob('test/ruby/**/*.rb').take(3)
 #     #<Pathname:test/ruby/box/a.1_1_0.rb>]
 ```
 
+The double-asterisk pattern matches directories recursively
+only when followed by the slash character `'/'`;
+otherwise it is equivalent to pattern `'*'`:
+
+```ruby
+Dir.glob('**') == Dir.glob('*') # => true
+```
+
+A pattern ending with `'/'` matches directory names only;
+each matched name ends with `'/'`:
+
+```ruby
+# Find the directories at the top level.
+Dir.glob('*/').take(3)  # => ["basictest/", "benchmark/", "bin/"]
+
+# Find all directories everywhere.
+Dir.glob('**/').take(3) # => ["basictest/", "benchmark/", "benchmark/gc/"]
+```
+
 The pattern may be escaped:
 
 ```ruby