From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#21581: 25.0.50; doc string of `load' Date: Mon, 28 Sep 2015 23:05:43 -0700 (PDT) Message-ID: <30d2221f-2d72-4985-91c9-4b1ff9447a45@default> References: <5d89275d-b8ad-4ced-b371-f40d24f08c21@default> <83oagldck2.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1443522562 29723 80.91.229.3 (29 Sep 2015 10:29:22 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 29 Sep 2015 10:29:22 +0000 (UTC) Cc: 21581@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Sep 29 12:29:09 2015 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Zgs9h-0000gX-58 for geb-bug-gnu-emacs@m.gmane.org; Tue, 29 Sep 2015 12:29:05 +0200 Original-Received: from localhost ([::1]:49711 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Zgs9g-0006h5-Ah for geb-bug-gnu-emacs@m.gmane.org; Tue, 29 Sep 2015 06:29:04 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50488) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Zgo3D-0008HM-49 for bug-gnu-emacs@gnu.org; Tue, 29 Sep 2015 02:06:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Zgo38-0008IR-WE for bug-gnu-emacs@gnu.org; Tue, 29 Sep 2015 02:06:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:58142) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Zgo38-0008IN-TW for bug-gnu-emacs@gnu.org; Tue, 29 Sep 2015 02:06:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1Zgo38-0008J8-GM for bug-gnu-emacs@gnu.org; Tue, 29 Sep 2015 02:06:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 29 Sep 2015 06:06:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 21581 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 21581-submit@debbugs.gnu.org id=B21581.144350674931914 (code B ref 21581); Tue, 29 Sep 2015 06:06:02 +0000 Original-Received: (at 21581) by debbugs.gnu.org; 29 Sep 2015 06:05:49 +0000 Original-Received: from localhost ([127.0.0.1]:47113 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Zgo2v-0008Ie-9Y for submit@debbugs.gnu.org; Tue, 29 Sep 2015 02:05:49 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:50046) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Zgo2s-0008IW-Nn for 21581@debbugs.gnu.org; Tue, 29 Sep 2015 02:05:47 -0400 Original-Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id t8T65j5P016332 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 29 Sep 2015 06:05:45 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userv0022.oracle.com (8.13.8/8.13.8) with ESMTP id t8T65i1b011610 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Tue, 29 Sep 2015 06:05:45 GMT Original-Received: from abhmp0007.oracle.com (abhmp0007.oracle.com [141.146.116.13]) by aserv0121.oracle.com (8.13.8/8.13.8) with ESMTP id t8T65inI021870; Tue, 29 Sep 2015 06:05:44 GMT In-Reply-To: <83oagldck2.fsf@gnu.org> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6691.5000 (x86)] X-Source-IP: userv0022.oracle.com [156.151.31.74] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:107035 Archived-At: > > Say that FILE is a string. >=20 > 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.)