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

Previous Next

Full log

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

Previous Next

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