Bug #9829
closedContradictions in docs for FileUtils::ln (and related functions)
Description
In the FileUtils module, to add simplicity and avoid duplication of code, a sort of coding paradigm exists for actions that read a filesystem object at one path and write a filesystem object at another.
These are the functions mv, cp and ln, along with similarly named functions that perform the same actions with slightly different options. What they all have in common is that they take two primary arguments -- first a "source" path and then a "destination" -- and also that they share the same code structure along with a couple of private helper methods to accomplish their work.
While this src/dest dynamic might be sufficient for creating hard/soft links given the level of abstraction Ruby is operating at with regard to the filesystem, it has resulted in the function parameters (to ln/ln_s/ln_sf/etc) themselves being named 'src' and 'dest' (presumably for consistency).
Since RDoc takes the function declaration (with parameter names) and makes it large and bold atop the function description, 'symlink(src, dest)', for example, is the first thing you see if you're trying to understand how to use this function. But in terms of symlinks in particular, 'source' and 'destination' each have double meanings. I.e. Is destination the target of the newly-created symlink? Or is it the path of the symlink?
Someone has clearly noticed this and tried to write in an alternate/duplicate function declaration somewhat below the real one with the arguments "old" and "new" this time rather than "src" and "dst", but this alternate declaration is still a lot lest prevalent than the official one, and new/old aren't the best terms to use anyway.
I would propose that the documentation and functions be updated to take the parameter pairs (target, link/alias) in the case of a single link and (targets, directory) in the case of multiple. These are the terms that man ln
uses.
Updated by zzak (zzak _) almost 10 years ago
- Status changed from Open to Assigned
Updated by Eregon (Benoit Daloze) almost 10 years ago
Agreed, this is very confusing.
Updated by stomar (Marcus Stollsteimer) about 7 years ago
- Status changed from Assigned to Closed
Applied in changeset r57811.
docs for FileUtils.ln methods
-
lib/fileutils.rb: [DOC] add clarifying call-seq's for FileUtil.ln,
ln_s, and ln_sf, with better argument names for the created link and
link target. Reported by Mike Vastola. [ruby-core:62532] [Bug #9829] -
lib/fileutils.rb: [DOC] further improve descriptions of FileUtils.ln
and related methods; improve examples: relative links probably won't
work in other dir, avoid `include', use more generic homedir name.
Updated by naruse (Yui NARUSE) about 7 years ago
- Backport set to 2.4: DONE
ruby_2_4 r57940 merged revision(s) 57811.