From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Evgeny Zajcev Newsgroups: gmane.emacs.devel Subject: Re: file-exists-p on empty string Date: Thu, 28 Feb 2019 03:08:54 +0300 Message-ID: References: <923ee6b0-0d19-4dae-bd58-6a576a892ef4@default> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="00000000000041ca0c0582e91982" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="184984"; mail-complaints-to="usenet@blaine.gmane.org" Cc: monnier@iro.umontreal.ca, emacs-devel To: Drew Adams Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Feb 28 01:20:37 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1gz9RE-000lxr-R4 for ged-emacs-devel@m.gmane.org; Thu, 28 Feb 2019 01:20:37 +0100 Original-Received: from localhost ([127.0.0.1]:52655 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gz9R8-00051p-Bn for ged-emacs-devel@m.gmane.org; Wed, 27 Feb 2019 19:20:30 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:47374) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gz9Qs-0004eS-8I for emacs-devel@gnu.org; Wed, 27 Feb 2019 19:20:15 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gz9GE-00085C-8a for emacs-devel@gnu.org; Wed, 27 Feb 2019 19:09:16 -0500 Original-Received: from mail-lf1-x12b.google.com ([2a00:1450:4864:20::12b]:42728) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gz9GD-0007bt-7l for emacs-devel@gnu.org; Wed, 27 Feb 2019 19:09:13 -0500 Original-Received: by mail-lf1-x12b.google.com with SMTP id p1so13826342lfk.9 for ; Wed, 27 Feb 2019 16:09:07 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=iXzGxerOrs6Xahk3lsyWzBFptdVPBbuVQzprYf8xtuc=; b=BQ3Wue4HTbN0MA6xWFAjQzhkX4BddDIsIYwGqqc8X68+yETB+zaddQXSPVAgYqaQa8 o/LvezTSBgyKP0sspAPWeIDsa9ET79R0B63TxD97zsh/QfetlX/Czm2AOGjsRPTw+Yy6 df9rHqrKY89qkIPNaxHbngNklNx+qpwPk/I6l8qsFJZUbHo9QhAIAmhx5JButDKG0ZOa wbHVsNgyMrzEqcMABVPVjk4ySrNtaE320W0rCxAu9Ejrn0VvkIym6QTCF7dhedO4vfcM ANw8sDD6eD8zEvlbolJQ7E79/9WwoGMML0PSpSH0ou2GQNC0tKoSZc10MUyvt4v170/w MeFQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=iXzGxerOrs6Xahk3lsyWzBFptdVPBbuVQzprYf8xtuc=; b=Yuu4x9CSOP5QsugO1Csu3deRtkT3s8ADXocmL8tIMTufF51lj2r8mWeswHONiCCeQ+ YhgEs7bIRUTitgqEmB9XgCbWXdib53rMAJfYAhKmOwoucj2u5y63RNhMIULR2Aoxgv9D wrvM3hNjlHGpAgQcDzzuo+VT5acigeUg6bYyLGM5T8ncEBi5QCf4vvfpY5Lve9eqlcTR IItuy7Ddfw51oqKYwiDm51HufoOzXHn2vYHHAeDwGsvyVv2RX5oRbgxg2N2UP96M3GBd MZlRQ+sgUzuO6pt4oKe2uxLQ9+ajXDItZFhogsU4SHySU85MxHeAh1b3PkLwl83bGmlX TEKw== X-Gm-Message-State: AHQUAuaGTqECkOrCrIvcEAlMAWvNTb+NOXGcLWa2tW6x4ypGgBeDko+H GkwXJuX19TotToxu1THguyuSVxvnwmWN60PROz7Coxv8+EU= X-Google-Smtp-Source: AHgI3IbMXY/wGzmaL3od7ORWBrVCdGlF2ym8JYuApE4I0X7sOv87dMy2NyZGbFfT6cduugpiAcq9Yir05dRmPtJGphg= X-Received: by 2002:a19:c744:: with SMTP id x65mr2374309lff.148.1551312546284; Wed, 27 Feb 2019 16:09:06 -0800 (PST) In-Reply-To: <923ee6b0-0d19-4dae-bd58-6a576a892ef4@default> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::12b X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:233687 Archived-At: --00000000000041ca0c0582e91982 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable =D1=87=D1=82, 28 =D1=84=D0=B5=D0=B2=D1=80. 2019 =D0=B3. =D0=B2 02:23, Drew = Adams : > > > > > The problem is that docstrings describe the behavior of a specifi= c > > > > > function, so they usually don't mention the more general aspects > that > > > > > affect all functions of a given subsystem, such as here the gener= al > > > > > 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 gi= ve > > > > at least some hint that this is not a filename, but just a name hin= t > > > > 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" --=20 lg --00000000000041ca0c0582e91982 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


=
=D1=87=D1=82, 28 =D1=84=D0=B5=D0=B2= =D1=80. 2019 =D0=B3. =D0=B2 02:23, Drew Adams <drew.adams@oracle.com>:
> > > > The problem is that do= cstrings describe the behavior of a specific
> > > > function, so they usually don't mention the more ge= neral 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 rep= eat this
> > >
> > >
> > > So, maybe FILENAME argument at least could be renamed to NAM= E to give
> > > at least some hint that this is not a filename, but just a n= ame hint
> > > which will be expanded and canonised to real filename?
> >
> > That's not good enough.=C2=A0 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.=C2=A0 But the doc string should say more
> > about it.=C2=A0 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.=C2=A0 Formal parameter names are a help,
nothing more.=C2=A0 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.=C2=A0 Sometimes not.

If a parameter name is truly misleading then it should
be changed.=C2=A0 I don't think that's the case here (for
either of the functions you mention).=C2=A0 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-do= cumenting editor"


--
lg
--00000000000041ca0c0582e91982--