Project

General

Profile

Actions

Bug #10075

closed

URI#join needs documentation of its behavior

Added by jxf (John Feminella) over 9 years ago. Updated over 9 years ago.

Status:
Closed
Assignee:
Target version:
ruby -v:
ruby 2.1.2p95 (2014-05-08 revision 45877) [x86_64-linux]
[ruby-core:63862]

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.


Related issues 1 (0 open1 closed)

Is duplicate of Ruby master - Bug #6057: URI - Nonsensical BehaviorClosedakira (akira yamada)Actions

Updated by drbrain (Eric Hodel) over 9 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 9 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.

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

Updated by jxf (John Feminella) over 9 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 9 years ago

On Mon, Jul 21, 2014 at 10:40 AM, 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 9 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 9 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.
Actions #7

Updated by mame (Yusuke Endoh) over 5 years ago

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

Also available in: Atom PDF

Like0
Like0Like0Like0Like0Like0Like0Like0