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

[Stefan Monnier]

> 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