Bug #10075: URI#join needs documentation of its behavior

• Status: Closed
• Assignee: zzak (zzak _)
• Target version: 2.2.0
• ruby -v: ruby 2.1.2p95 (2014-05-08 revision 45877) [x86_64-linux]
• Backport: 2.0.0: UNKNOWN, 2.1: UNKNOWN

[jxf (John Feminella)]

The documentation for URI.join says:

"Joins URIs."

Let's look at what a similar join method documentation 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.

[drbrain (Eric Hodel)]

• Subject changed from URI#join seems to violate Principle of Least Surprise to URI#join needs documentation of its behavior
• Category set to doc

I have changed this to a doc bug, the behavior does not surprise me, I expect it to behave as it does.

[phluid61 (Matthew Kerwin)]

Eric Hodel wrote:

I have changed this to a doc bug, the behavior does not surprise me, I expect it to behave as it does.

It surprised me. The operation it performs appears to be "resolve relative" [1], but, like OP, from the name alone I'd have expected "concatenate with separators".

I think the case could be made that either/both operation could be called "join", but I think there's a better name for both. Anyway, better documentation would resolve the issue.

[1] http://tools.ietf.org/html/rfc3986#section-5.2

[jxf (John Feminella)]

Eric Hodel wrote:

I have changed this to a doc bug, the behavior does not surprise me, I expect it to behave as it does.

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).

However, URL.join doesn't work in this way. That's why I found it surprising, and reading the documentation didn't alleviate my surprise. So, better documentation would be an improvement, but I think it would be a bigger improvement if it worked more like the other join methods to begin with.

[avdi (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.

[zzak (zzak _)]

• Status changed from Open to Assigned
• Assignee set to zzak (zzak _)
• Target version set to 2.2.0

I will try to improve the explanation

[zzak (zzak _)]

• Status changed from Assigned to Closed
• % Done changed from 0 to 100

Applied in changeset r46979.

---

• lib/uri/common.rb: [DOC] [Bug #10075] Clarify how URI.join arguments
  are handled by RFC3986, originall reported by John Feminella.

[mame (Yusuke Endoh)]

• Is duplicate of Bug #6057: URI - Nonsensical Behavior added