> > > > 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.
Totally, that is why "Emacs is an extensible self-documenting editor"