bug#10489: 24.0.92; dired-do-copy may create infinite directory hierarchy

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Fri, 13 Jan 2012 20:55:23 -0500
> Cc: 10489@debbugs.gnu.org, Thierry Volpiatto <thierry.volpiatto@gmail.com>
> 
> >> There's a crucial line missing between the above two.  It should clearly
> >> document what this function is expected to do.  E.g. it should make it
> >> clear if (and if so, to what extent) the function is allowed to refer to
> >> the actual file system(s) as opposed to only relying on the
> >> provided strings.
> > If the file name strings are not obviously equal, `file-truename' will
> 
> I don't mean "document what the code currently does" but "document
> what the code should do".

Same thing in this case.  If we want to resolve the various cases of
equivalent file names, we have no alternative but hitting the disk.

> >   "Return non-nil if NAME1 and NAME2 refer to the same file in the file system.
> > If either name is not absolute, then it is expanded relative to
> > DIR (if given) or `default-directory' for the test."
> 
> That description is too vague: an implementation based on comparing
> file-attributes would seem to fit, whereas it's clearly not the semantic
> we want to provide.

Sorry, I'm not following.  Why does a possibly different
implementation make the doc string "too vague"?  IOW, the doc string
_should_ be sufficiently "vague" to allow a change in the
implementation without breaking the API or the semantics, right?