Bug #10075
closedURI#join needs documentation of its behavior
Description
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.
Updated by drbrain (Eric Hodel) over 10 years ago
- 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.
Updated by phluid61 (Matthew Kerwin) over 10 years ago
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.
Updated by jxf (John Feminella) over 10 years ago
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.
Updated by avdi (Avdi Grimm) over 10 years ago
On Mon, Jul 21, 2014 at 10:40 AM, jxf+ruby@jxf.me 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.
Updated by zzak (zzak _) over 10 years ago
- 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
Updated by zzak (zzak _) over 10 years ago
- 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.
Updated by mame (Yusuke Endoh) almost 6 years ago
- Is duplicate of Bug #6057: URI - Nonsensical Behavior added