> > The problem is that docstrings describe the behavior of a specific
> function, so they usually don't mention the more general aspects that
> affect all functions of a given subsystem, such as here the general
> treatment of the empty string when used as a file name. Otherwise,
> every file-name-manipulating function would have to repeat this
> information in its docstring.
>
> So, maybe FILENAME argument at least could be renamed to NAME to give
> at least some hint that this is not a filename, but just a name hint
> which will be expanded and canonised to real filename?
That's not good enough. It might make sense
to you now, now that you know something about
how the input is interpreted as a file name.
The parameter name FILENAME is more appropriate
than NAME. But the doc string should say more
about it. You can't rely on just the parameter
name to convey all of the meaning that you're
(now) reading into it.
But what to do with `file-name-directory` function, which returns `nil` to empty string, while `file-exists-p` returns `t', and both of them gets FILENAME as argument ?