[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Emacs-diffs] /srv/bzr/emacs/trunk r107428: * doc/lispref/files.texi
From: |
Stefan Monnier |
Subject: |
Re: [Emacs-diffs] /srv/bzr/emacs/trunk r107428: * doc/lispref/files.texi: (files-equal-p, file-subdir-of-p): Add documentation. |
Date: |
Sat, 25 Feb 2012 17:41:04 -0500 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.0.93 (gnu/linux) |
> 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.
> 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.
> 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").
Maybe we should take it the other way and say that it returns non-nil iff
dir2 is one of the ancestors of dir1.
> +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.
> +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.
> +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.
Stefan