[ruby-core:62533] [ruby-trunk - Bug #9829] [Assigned] Contradictions in docs for FileUtils::ln (and related functions)

Issue #9829 has been updated by Zachary Scott.

Status changed from Open to Assigned

----------------------------------------
Bug #9829: Contradictions in docs for FileUtils::ln (and related functions)
https://bugs.ruby-lang.org/issues/9829#change-46688

* Author: Mike Vastola
* Status: Assigned
* Priority: Normal
* Assignee: Zachary Scott
* Category: doc
* Target version: 
* ruby -v: HEAD (r45880 at present)
* Backport: 
----------------------------------------
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.





-- 
https://bugs.ruby-lang.org/