GNU bug report logs - #18201
24.4.50; doc string of `file-accessible-directory-p'

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 18201 in the body.
You can then email your comments to 18201 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: 24.4.50; doc string of `file-accessible-directory-p'
Date: Tue, 5 Aug 2014 12:13:22 -0700 (PDT)

The doc string:

 Return t if file FILENAME names a directory you can open.
 For the value to be t, FILENAME must specify the name of a directory as a file,
 and the directory must allow you to open files in it.  In order to use a
 directory as a buffer's current directory, this predicate must return true.
 A directory name spec may be given instead; then the value is t
 if the directory so specified exists and really is a readable and
 searchable directory.

1. Unless other non-nil values can be returned, in which case they need
   to be documented, the doc should refer to "non-nil" (or "true"), not
   to `t'.

2. "Return t if file FILENAME names a directory..." is wrong.  It should
   say just "FILENAME", not "file FILENAME".  A file does not name
   anything.  A file name names something (in this case, a directory).

#1 and #2 are problems for other, related doc strings, as well.
Presumably someone renamed the parameter from FILE to FILENAME without
adapting the doc string properly (?).

3. The biggest problem with this doc string is that it refers to
   something called a "directory name spec", without either (1) saying
   what that is or (2) telling you where to find this information.  You
   CANNOT understand this doc string without knowing what "directory
   name spec" means.

4. The lines of text should not be longer than 70 chars (except the
   first, which can be a little longer.  The second line is 79 chars.
   Please fill all but the first line.

In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-06-28 on ODIEONE
Bzr revision: 117431 rgm <at> gnu.org-20140628015517-eku6hj8mpgcvfnso
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 18201 <at> debbugs.gnu.org
Subject: Re: bug#18201: 24.4.50; doc string of `file-accessible-directory-p'
Date: Sat, 30 Apr 2016 01:25:33 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

>  Return t if file FILENAME names a directory you can open.
>  For the value to be t, FILENAME must specify the name of a directory as a file,
>  and the directory must allow you to open files in it.  In order to use a
>  directory as a buffer's current directory, this predicate must return true.
>  A directory name spec may be given instead; then the value is t
>  if the directory so specified exists and really is a readable and
>  searchable directory.
>
> 1. Unless other non-nil values can be returned, in which case they need
>    to be documented, the doc should refer to "non-nil" (or "true"), not
>    to `t'.

No, it does return precisely t.  Perhaps later it'll return other
values.

> 2. "Return t if file FILENAME names a directory..." is wrong.  It should
>    say just "FILENAME", not "file FILENAME".  A file does not name
>    anything.  A file name names something (in this case, a directory).

Fixed.

> 3. The biggest problem with this doc string is that it refers to
>    something called a "directory name spec", without either (1) saying
>    what that is or (2) telling you where to find this information.  You
>    CANNOT understand this doc string without knowing what "directory
>    name spec" means.

Hm...  I don't know what the doc string means here.  And looking at the
code, I still don't understand.  Anybody?

> 4. The lines of text should not be longer than 70 chars (except the
>    first, which can be a little longer.  The second line is 79 chars.
>    Please fill all but the first line.

Fixed.

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

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 18201 <at> debbugs.gnu.org
Subject: Re: bug#18201: 24.4.50; doc string of `file-accessible-directory-p'
Date: Sat, 29 May 2021 06:02:42 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

>> 3. The biggest problem with this doc string is that it refers to
>>    something called a "directory name spec", without either (1) saying
>>    what that is or (2) telling you where to find this information.  You
>>    CANNOT understand this doc string without knowing what "directory
>>    name spec" means.
>
> Hm...  I don't know what the doc string means here.  And looking at the
> code, I still don't understand.  Anybody?

The manual had a better explanation, so I copied that over in Emacs 28.

-- 
(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.