Re: [Emacs-diffs] /srv/bzr/emacs/trunk r107428: * doc/lispref/files.texi: (files-equal-p, file-subdir-of-p): Add documentation.

[Thierry Volpiatto]

Stefan Monnier <address@hidden> writes:

>> address@hidden files-equal-p file1 file2
>> +This function return @code{t} if the files @var{file1} and @var{file2} name
>> +the same file.
>> +Comparison is made with the @code{file-attributes} of both files. 
>> address@hidden defun
>
> The doc should not describe the implementation but the behavior, so it
> should not say that the comparison is made with file-attributes.
Ok.

>> address@hidden file-subdir-of-p dir1 dir2
>> +This function return @code{t}
>
> Usually we prefer to say non-nil for boolean return values, so as to
> leave some extra freedom to the implementation.
I just looked at the doc of file-regular-p, ok I will fix.


>> if directory @var{dir1} is a subdirectory
>> +of @var{dir2} or if @var{dir1} and @var{dir2} are the same directory.
>
> This might be taken to mean "don't return t if dir1 is a subdir of
> a subdir of dir2" (i.e. return t only if dir1 is either 0 or 1 level
> further down than dir2").
It doesn't.

> Maybe we should take it the other way and say that it returns non-nil iff
> dir2 is one of the ancestors of dir1.
Ok.

>> +Arguments @var{dir1} and @var{dir2} must be existing directories,
>
> That's a current limitation, and might be lifted in the future.
> Maybe dir2's existence is a prerequisite, but "a/b/c" is a subdir of "a"
> whether or not "a/b" exists, so I don't think we should force dir1 to exist.
In this case the comparison have to be with string= but no more with
files-equal-p (files-attributes).

>> +otherwise, return nil.
>
> And at least we should not force our function to return nil when
> encountering that limitation, since it means we can't lift this
> limitation without breaking documented behavior.
What do you want to return instead?

>> +Check is done by building a directory name based on equality of differents
>> +components of both directory names, if this resulting directory name
>> +is equal to @var{dir2}, we assume directory @var{dir1}
>> +is a subdirectory of @var{dir2}.
>
> Again, the documentation should not describe the implementation.
Ok.

-- 
  Thierry
Get my Gnupg key:
gpg --keyserver pgp.mit.edu --recv-keys 59F29997