[ruby-core:63924] [ruby-trunk - Bug #10075] URI#join needs documentation of its behavior

Issue #10075 has been updated by Avdi Grimm.


 On Mon, Jul 21, 2014 at 10:40 AM, <[e-mail]> wrote:
 
 > Here's my thoughts on this: every other Ruby method I can think of named
 > `#join` works by concatenating its arguments together with a separator
 > (possibly with some additional logic to remove redundant separators and
 > such).
 >
 
 This has caught me by surprise multiple times as well. I don't question the
 need for a method with these semantics, but the choice of name "join" seems
 misleading. Too late to change it now, but I wouldn't mind seeing it
 aliased to a less surprising name (perhaps "#merge_path", per RFC3986) and
 the "join" version eventually deprecated.

----------------------------------------
Bug #10075: URI#join needs documentation of its behavior
https://bugs.ruby-lang.org/issues/10075#change-47951

* Author: John Feminella
* Status: Open
* Priority: Normal
* Assignee: 
* Category: doc
* Target version: 
* ruby -v: ruby 2.1.2p95 (2014-05-08 revision 45877) [x86_64-linux]
* Backport: 2.0.0: UNKNOWN, 2.1: UNKNOWN
----------------------------------------
The [documentation](http://www.ruby-doc.org/stdlib-2.1.2/libdoc/uri/rdoc/URI.html#method-c-join) for `URI.join` says:

> "Joins URIs."

Let's look at what a similar `join` method [documentation](http://www.ruby-doc.org/core-2.1.2/File.html#method-c-join) says, on `File`:

> Returns a new string formed by joining the strings using File::SEPARATOR.

That seems pretty clear. Indeed, we get:

~~~
File.join 'path', 'to', 'join'
# => "path/to/join"
~~~

which is what we expected. What do we get if we try the natural `URI` equivalent?

~~~
> URI.join('http://example.com', 'foo', 'bar')
~~~

We probably expect something like:

~~~
# => "http://example.com/foo/bar"
~~~

but we'll actually get

~~~
# => "http://example.com/bar"
~~~

This seems surprising and counterintuitive, even if it matches the documentation behavior, because the documentation doesn't explain why that's the case. I think if Ruby is going to be surprising in that way, it needs to explain that to users in the documentation.



-- 
https://bugs.ruby-lang.org/