From: e@... Date: 2014-07-26T16:53:50+00:00 Subject: [ruby-core:64062] [ruby-trunk - Bug #10075] [Assigned] URI#join needs documentation of its behavior Issue #10075 has been updated by Zachary Scott. 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 ---------------------------------------- Bug #10075: URI#join needs documentation of its behavior https://bugs.ruby-lang.org/issues/10075#change-48072 * Author: John Feminella * Status: Assigned * Priority: Normal * Assignee: Zachary Scott * Category: doc * Target version: current: 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 ---------------------------------------- The [documentation](http://www.ruby-doc.org/stdlib-2.1.2/libdoc/uri/rdoc/URI.html#method-c-join) for `URI.join` says: > "Joins URIs." Let's look at what a similar `join` method [documentation](http://www.ruby-doc.org/core-2.1.2/File.html#method-c-join) 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. -- https://bugs.ruby-lang.org/