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

Previous Next

Full log

View this message in rfc822 format

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 18201 <at> debbugs.gnu.org
Subject: 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

Previous Next

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