Project

General

Profile

Bug #9829

Contradictions in docs for FileUtils::ln (and related functions)

Added by MikeVastola (Mike Vastola) over 3 years ago. Updated 7 months ago.

Status:
Closed
Priority:
Normal
Target version:
-
ruby -v:
HEAD (r45880 at present)
Backport:
[ruby-core:62532]

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.

Associated revisions

Revision 57811
Added by stomar (Marcus Stollsteimer) 8 months ago

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. [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.

Revision 57940
Added by naruse (Yui NARUSE) 7 months ago

merge revision(s) 57811: [Backport #9829]

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.  [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.

History

#1 [ruby-core:62533] Updated by zzak (Zachary Scott) over 3 years ago

  • Status changed from Open to Assigned

#2 [ruby-core:62535] Updated by Eregon (Benoit Daloze) over 3 years ago

Agreed, this is very confusing.

#3 Updated by stomar (Marcus Stollsteimer) 8 months 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. [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.

#4 [ruby-core:80075] Updated by naruse (Yui NARUSE) 7 months ago

  • Backport set to 2.4: DONE

ruby_2_4 r57940 merged revision(s) 57811.

Also available in: Atom PDF