[DOC] Doc for Pathname#+ #81
Conversation
lib/pathname_builtin.rb
Outdated
| # When +other+ specifies a relative path (see #relative?), | ||
| # equivalent to <tt>Pathname.new(self.to_s + other.to_s)</tt>: |
There was a problem hiding this comment.
That's not the case, e.g.:
irb(main):002> Pathname("/a/b") + Pathname("../c")
=> #<Pathname:/a/c>
There was a problem hiding this comment.
Wow! Thanks, @eregon! I had no idea (from the existing doc) of this handling. I should have consulted the tests.
| # call-seq: | ||
| # self + other -> new_pathname |
There was a problem hiding this comment.
Is there any advantage to have a call-seq for a method defined in Ruby?
There was a problem hiding this comment.
I think so.
- The "self + other" idiom makes clear the "binary-operator" nature of the metho; it is seen in many other places in Ruby documentation.
- The "-> new_pathname" is useful information.
There was a problem hiding this comment.
That's all redundant for + which is always binary and always returns a new value (doesn't mutate the receiver).
There was a problem hiding this comment.
Always binary in Pathname, but other classes have @+, so the distinction is not fatuous.
No one (at least no one I know) writes pn.+('baz'), so self + other will seem natural to most?
new_pathname is indeed redundant, but is the widespread custom in the Ruby core documentation.
|
What's the issue with the existing docs? IMO they are already fine, and concise is IMO good as long as still clear. |
| # Extra component separators (<tt>'/'</tt>) are removed: | ||
| # | ||
| # Pathname.new('/a/b/') + 'c' # => #<Pathname:/a/b/c> | ||
| # | ||
| # Extra current-directory components (<tt>'.'</tt>) are removed: | ||
| # | ||
| # Pathname.new('a') + '.' # => #<Pathname:a> | ||
| # Pathname.new('.') + 'a' # => #<Pathname:a> | ||
| # Pathname.new('.') + '.' # => #<Pathname:.> | ||
| # | ||
| # Parent-directory components (<tt>'..'</tt>) are: | ||
| # | ||
| # - Resolved, when possible: | ||
| # | ||
| # Pathname.new('a') + '..' # => #<Pathname:.> | ||
| # Pathname.new('a/b') + '..' # => #<Pathname:a> | ||
| # Pathname.new('/') + '../a' # => #<Pathname:/a> | ||
| # Pathname.new('a') + '../b' # => #<Pathname:b> | ||
| # Pathname.new('a/b') + '../c' # => #<Pathname:a/c> | ||
| # Pathname.new('a//b/c') + '../d//e' # => #<Pathname:a//b/d//e> | ||
| # | ||
| # - Removed, when not needed: | ||
| # | ||
| # Pathname.new('/') + '..' # => #<Pathname:/> | ||
| # | ||
| # - Retained, when needed: | ||
| # | ||
| # Pathname.new('..') + '..' # => #<Pathname:../..> | ||
| # Pathname.new('..') + '../a' # => #<Pathname:../../a> | ||
| # | ||
| # When +other+ specifies an absolute path (see #absolute?), | ||
| # equivalent to <tt>Pathname.new(other.to_s)</tt>: | ||
| # | ||
| # Pathname.new('/a') + '/b/c' # => #<Pathname:/b/c> | ||
| # | ||
| # Occurrences of <tt>'/'</tt>, <tt>'.'</tt>, and <tt>'..'</tt> are preserved: | ||
| # | ||
| # Pathname.new('/a') + '//b//c/./../d' # => #<Pathname://b//c/./../d> | ||
| # | ||
| # This method does not access the file system, so +other+ need not represent | ||
| # an existing (or even a valid) file or directory path: | ||
| # | ||
| # Pathname.new('/var') + 'nosuch:ever' # => #<Pathname:/var/nosuch:ever> |
There was a problem hiding this comment.
This looks potentially useful information, OTOH it also describes a lot of things, some of which might be implementation details.
There was a problem hiding this comment.
I don't see implementation details here. These behaviors are user-visible, and are mostly taken directly from the tests.
2 participants
No description provided.