чт, 28 февр. 2019 г. в 02:23, Drew Adams <drew.adams@oracle.com>:

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


-- 
lg