URI#join needs documentation of its behavior
The documentation for
Let's look at what a similar
join method documentation says, on
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.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.