Bug #10075

URI#join needs documentation of its behavior

Added by John Feminella 12 months ago. Updated 11 months 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 11 months 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 11 months 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 12 months 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 12 months 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 12 months 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 11 months 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 11 months 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 11 months 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