GNU bug report logs - #21581
25.0.50; doc string of `load'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 21581 in the body.
You can then email your comments to 21581 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.0.50; doc string of `load'
Date: Mon, 28 Sep 2015 10:22:51 -0700 (PDT)

Say that FILE is a string.

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-09-23
Bzr revision: 325200ac1dcf5bed6918ea827d8a48d89487e083
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=i686-pc-mingw32 --enable-checking=yes,glyphs'

Message #8 received at 21581 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 21581 <at> debbugs.gnu.org
Subject: Re: bug#21581: 25.0.50; doc string of `load'
Date: Tue, 29 Sep 2015 08:22:53 +0300

> Date: Mon, 28 Sep 2015 10:22:51 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> Say that FILE is a string.

  load is a built-in function in ‘C source code’.

  (load FILE &optional NOERROR NOMESSAGE NOSUFFIX MUST-SUFFIX)

  Execute a file of Lisp code named FILE.

Do you really mean we need to say explicitly that a file's name is a
string in Emacs?  What else can it be?  From the ELisp manual:

  24.8 File Names
  ===============

  Files are generally referred to by their names, in Emacs as elsewhere.
  File names in Emacs are represented as strings.  The functions that
  operate on a file all expect a file name argument.

I think this is so basic that we can always say "a file's name" and
assume the reader must know it can only be a string.

Message #11 received at 21581 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21581 <at> debbugs.gnu.org
Subject: RE: bug#21581: 25.0.50; doc string of `load'
Date: Mon, 28 Sep 2015 23:05:43 -0700 (PDT)

> > Say that FILE is a string.
> 
> Do you really mean we need to say explicitly that a file's name is a
> string in Emacs?

That's my suggestion - do as you like.  No, I'm not saying
that we NEED to.  I'm suggesting that it could help.

> From the ELisp manual:
>   Files are generally referred to by their names, in Emacs as elsewhere.
>   File names in Emacs are represented as strings.  The functions that
>   operate on a file all expect a file name argument.

That's fine.  But a user looking at the doc string doesn't see that.
If you want to add a link to that manual node to the doc string,
great.

The very fact that that last sentence was explicitly added to
the manual suggests that it is not obvious that file arguments
are strings.  If it were obvious then even that whole section
about file names could perhaps be removed.  (And again, that
information is absent from the doc string.)

> I think this is so basic that we can always say "a file's name" and
> assume the reader must know it can only be a string.

Yes, maybe.  But I think it's also basic to specify the types
of parameters in doc strings.  (It could also help a bit to
call the parameter FILENAME intead of FILE.)

The doc strings of some functions (but yes, only a minority)
already explicitly mention that the arg is a string:

add-name-to-file
autoload
copy-file
do-after-load-evaluation
eval-after-load
find-buffer-visiting
get-file-buffer
load-history-regexp
make-symbolic-link
rename-file

(Consider also that some other, somewhat similar functions that load
Lisp code allow a symbol parameter - `require', for instance.
Granted, a feature is not a file.  Still, I think it could help
to make clear that FILE here is a string.)

Message #14 received at 21581 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21581 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#21581: 25.0.50; doc string of `load'
Date: Sun, 01 May 2016 00:19:43 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

> I think this is so basic that we can always say "a file's name" and
> assume the reader must know it can only be a string.

I agree.  Closing.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.