Bug #10075

URI#join needs documentation of its behavior

Added by John Feminella about 1 year ago. Updated about 1 year ago.

[ruby-core:63862]
Status:Closed
Priority:Normal
Assignee:Zachary Scott
ruby -v:ruby 2.1.2p95 (2014-05-08 revision 45877) [x86_64-linux] Backport:2.0.0: UNKNOWN, 2.1: UNKNOWN

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.

Associated revisions

Revision 46979
Added by Zachary Scott about 1 year ago

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

Revision 46979
Added by Zachary Scott about 1 year ago

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

History

#1 Updated by Eric Hodel about 1 year 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.

#2 Updated by Matthew Kerwin about 1 year 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.

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

#3 Updated by John Feminella about 1 year 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.

#4 Updated by Avdi Grimm about 1 year 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.

#5 Updated by Zachary Scott about 1 year ago

  • Status changed from Open to Assigned
  • Assignee set to Zachary Scott
  • Target version set to current: 2.2.0

I will try to improve the explanation

#6 Updated by Zachary Scott about 1 year 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.

Also available in: Atom PDF