> > > > 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
> > >
> > >
> > > 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 ?

The doc string of each should describe its parameters
and return values.  Formal parameter names are a help,
nothing more.  Sometimes a parameter name is clear
enough that it can be used inline in a sentence in
such a way that the sentence clarifies its meaning
or its name clarifies the sentence.  Sometimes not.

If a parameter name is truly misleading then it should
be changed.  I don't think that's the case here (for
either of the functions you mention).  But others
might have different opinions.

The point is that the doc string should describe the
function: its behavior, its inputs, its return value,
and its side effects.