Misc #17154
open
Update Pathname Documentation to Clarify Expected Behavior
Description
I would like to suggest adding a sentence to the documentation for Pathname to make clear the unusual behavior of Pathname#+ when an absolute path is included in the arguments. In such a situation, Pathname#+ drops the paths prior to the last absolute path which I understand to be the intended behavior, but it is not obviously intended, only showing up tangentially as an example in the documentation.
p3 = p1 + "/etc/passwd" # Pathname:/etc/passwd
The Pathname documentation states that " All functionality from File, FileTest, and some from Dir and FileUtils is included, in an unsurprising way ..." and later when referring to core methods such as Pathname#+ "These methods are effectively manipulating a String , because that's all a path is." However, similar uses of both File and String would produce the expected result of including all of the arguments:
s1 = "/usr"
s2 = s1 + "/etc/passwd" # "/usr/etc/passwd"
f1 = File.new("/usr" + "/etc/passwd") # (No such file or directory @ rb_sysopen - /usr/etc/passwd)
A bug report was previously filed to "fix" this functionality (Bug #15564: Pathname#+(pathpart) returns pathpart when pathpart is absolute), not understanding it to be intentional. Other common help websites such as Stack Overflow also show users who do not expect this behavior from this method. Adding a statement to the documentation for the Pathname#+ method will make it clear to users exactly what to expect and that this is the intended behavior. I would suggest simply the following, the first sentence of which is already present:
Appends a pathname fragment to self to produce a new Pathname object. If an absolute path is provided as any of the arguments, discards all arguments prior to the last absolute path provided.
I appreciate your consideration of this request.
ruby -v: ruby 2.7.1p83 (2020-03-31 revision a0c7c23c9c) [x86_64-linux]
Updated by 
Updated by