[DOC] Harmonize join methods

Author: BurdetteLamar

array.c

@@ -3107,28 +3107,20 @@ rb_ary_join(VALUE ary, VALUE sep)
  *  call-seq:
  *    join(separator = $,) -> new_string
  *
- *  Returns the new string formed by joining the converted elements of +self+;
- *  for each element +element+:
+ *  Returns the new string formed by joining the string-converted elements of +self+
+ *  with the given +separator+ (defaults to <tt>$,</tt>):
  *
- *  - Converts recursively using <tt>element.join(separator)</tt>
- *    if +element+ is a <tt>kind_of?(Array)</tt>.
- *  - Otherwise, converts using <tt>element.to_s</tt>.
+ *    $,                  # => nil
+ *    %w[].join           # => ""
+ *    %w[foo].join        # => "foo"
+ *    a = %w[foo bar baz] # => ["foo", "bar", "baz"]
+ *    a.join              # => "foobarbaz"
+ *    a.join('|')         # => "foo|bar|baz"
+ *    a.join(' :|: ')     # => "foo :|: bar :|: baz"
  *
- *  With no argument given, joins using the output field separator, <tt>$,</tt>:
+ *  Flattens and joins nested arrays:
  *
- *    a = [:foo, 'bar', 2]
- *    $, # => nil
- *    a.join # => "foobar2"
- *
- *  With string argument +separator+ given, joins using that separator:
- *
- *    a = [:foo, 'bar', 2]
- *    a.join("\n") # => "foo\nbar\n2"
- *
- *  Joins recursively for nested arrays:
- *
- *   a = [:foo, [:bar, [:baz, :bat]]]
- *   a.join # => "foobarbazbat"
+ *    [:foo, [:bar, [:baz, :bat]]].join # => "foobarbazbat"
  *
  *  Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
  */

file.c

@@ -5615,12 +5615,14 @@ rb_file_join(long argc, VALUE *args)
 }
 /*
  *  call-seq:
- *     File.join(string, ...)  ->  string
+ *     File.join(*objects) -> new_string
  *
- *  Returns a new string formed by joining the strings using
- *  <code>"/"</code>.
+ *  Returns a new string formed by joining the given string-converted +objects+
+ *  with character <tt>'/'</tt>:
  *
- *     File.join("usr", "mail", "gumby")   #=> "usr/mail/gumby"
+ *    File.join                      # => ""
+ *    File.join('foo')               # => "foo"
+ *    File.join('foo', 'bar', 'baz') # => "foo/bar/baz"
  *
  */
 

pathname_builtin.rb

@@ -759,17 +759,16 @@ def plus(path1, path2) # :nodoc:
   end
   private :plus
 
+  # call-seq:
+  #   join(*objects) -> new_pathname
   #
-  # Joins the given pathnames onto +self+ to create a new Pathname object.
-  # This is effectively the same as using Pathname#+ to append +self+ and
-  # all arguments sequentially.
+  # Joins the string-converted given +objects+ to the string path in +self+;
+  # returns a new pathname containing the joined string:
   #
-  #   path0 = Pathname.new("/usr")                # Pathname:/usr
-  #   path0 = path0.join("bin/ruby")              # Pathname:/usr/bin/ruby
-  #       # is the same as
-  #   path1 = Pathname.new("/usr") + "bin/ruby"   # Pathname:/usr/bin/ruby
-  #   path0 == path1
-  #       #=> true
+  #   Pathname('foo').join                  # => #<Pathname:foo>
+  #   Pathname('foo').join('bar')           # => #<Pathname:foo/bar>
+  #   Pathname('foo').join('bar', 'baz')    # => #<Pathname:foo/bar/baz>
+  #   Pathname('foo').join(Pathname('bar')) # => #<Pathname:foo/bar>
   #
   def join(*args)
     return self if args.empty?

set.c

@@ -686,9 +686,23 @@ set_i_to_set(VALUE set)
 
 /*
  *  call-seq:
- *    join(separator=nil)-> new_string
+ *    join(separator = $,) -> new_string
+ *
+ *  Returns the new string formed by joining the string-converted elements of +self+
+ *  with the given +separator+ (defaults to <tt>$,</tt>):
+ *
+ *    $,                       # => nil
+ *    Set[].join               # => ""
+ *    Set[%w[foo]].join        # => "foo"
+ *    s = Set[%w[foo bar baz]] # => Set[["foo", "bar", "baz"]]
+ *    s.join                   # => "foobarbaz"
+ *    s.join('|')              # => "foo|bar|baz"
+ *    s.join(' :|: ')          # => "foo :|: bar :|: baz"
+ *
+ *  Flattens and joins nested arrays:
+ *
+ *    Set[[:foo, [:bar, [:baz, :bat]]]].join0 # => "foobarbazbat"
  *
- *  Returns a string created by converting each element of the set to a string.
  */
 static VALUE
 set_i_join(int argc, VALUE *argv, VALUE set)