bug#18201: 24.4.50; doc string of `file-accessible-directory-p'

bug#18201: 24.4.50; doc string of `file-accessible-directory-p'

[Drew Adams]

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

bug#18201: 24.4.50; doc string of `file-accessible-directory-p'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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

bug#18201: 24.4.50; doc string of `file-accessible-directory-p'

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@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