Subject: bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

From: Michael Albinus <[email-masked]>
Date: Mon, 28 Feb 2022 09:03:03 +0100

Drew Adams <[email-masked]> writes:

Hi Drew,

> OK, I see that the doc string of `file-remote-p' -
> but NOT its description in the Elisp manual - does
> at least call out what happens if the arg FILE is
> a relative file name: the function just returns nil.
>
> That doesn't invalidate the rest of what this bug
> report says.  Each function's description should say
> what kind of file-name argument it expects, and if
> it handles both relative and absolute file names,
> how it does so - how it treats each kind.

We could discuss forever, whether this information is needed in the
Elisp manual. In my understanding, the manual is not an "extended
docstring". It is rather meant to give another view, with the help of
examples etc. IIRC, it isn't said anywhere, that a manual entry must be
comprehensive w/o the docstring.

> Users shouldn't have to search the Elisp code base
> to try to figure out whether they might need to
> apply `expand-file-name' to a file name before
> passing it to some function.

There's no need to read the implementation. The docstring of
file-remote-p is clear about this point.

Best regards, Michael.