unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#18201: 24.4.50; doc string of `file-accessible-directory-p'
@ 2014-08-05 19:13 Drew Adams
  2016-04-29 23:25 ` Lars Ingebrigtsen
  0 siblings, 1 reply; 3+ messages in thread
From: Drew Adams @ 2014-08-05 19:13 UTC (permalink / raw)
  To: 18201

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





^ permalink raw reply	[flat|nested] 3+ messages in thread

* bug#18201: 24.4.50; doc string of `file-accessible-directory-p'
  2014-08-05 19:13 bug#18201: 24.4.50; doc string of `file-accessible-directory-p' Drew Adams
@ 2016-04-29 23:25 ` Lars Ingebrigtsen
  2021-05-29  4:02   ` Lars Ingebrigtsen
  0 siblings, 1 reply; 3+ messages in thread
From: Lars Ingebrigtsen @ 2016-04-29 23:25 UTC (permalink / raw)
  To: Drew Adams; +Cc: 18201

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





^ permalink raw reply	[flat|nested] 3+ messages in thread

* bug#18201: 24.4.50; doc string of `file-accessible-directory-p'
  2016-04-29 23:25 ` Lars Ingebrigtsen
@ 2021-05-29  4:02   ` Lars Ingebrigtsen
  0 siblings, 0 replies; 3+ messages in thread
From: Lars Ingebrigtsen @ 2021-05-29  4:02 UTC (permalink / raw)
  To: Drew Adams; +Cc: 18201

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





^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2021-05-29  4:02 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-08-05 19:13 bug#18201: 24.4.50; doc string of `file-accessible-directory-p' Drew Adams
2016-04-29 23:25 ` Lars Ingebrigtsen
2021-05-29  4:02   ` Lars Ingebrigtsen

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).