file-name-as-directory: Update doc. string

file-name-as-directory: Update doc. string

[Tino Calancha]

Hi,

Doc. string for `file-name-as-directory' is out of date; this
doc. string suggests that expand-file-name only accepts
a directory name as its second argument.  It is explicitely
mentioned in expand-file-name doc. string that the second
argument can be a directory file name as well.

This is just a doc fix: should go to emacs-25 branch?
Regards,
Tino
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
From 2e5dc72a2c6f354ece75b552c3f145d7b9d7367a Mon Sep 17 00:00:00 2001
From: Tino Calancha <tino.calancha@gmail.com>
Date: Mon, 12 Sep 2016 15:54:45 +0900
Subject: [PATCH] file-name-as-directory: Doc fix

* src/fileio.c (file-name-as-directory): expand-file-name accepts
as its secong argument both, the directory name and a directory's
file name.
---
  src/fileio.c | 3 +--
  1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/fileio.c b/src/fileio.c
index c3b2be7..638ccf8 100644
--- a/src/fileio.c
+++ b/src/fileio.c
@@ -508,8 +508,7 @@ DEFUN ("file-name-as-directory", 
Ffile_name_as_directory,
         doc: /* Return a string representing the file name FILE 
interpreted as a directory.
  This operation exists because a directory is also a file, but its name as
  a directory is different from its name as a file.
-The result can be used as the value of `default-directory'
-or passed as second argument to `expand-file-name'.
+The result can be used as the value of `default-directory'.
  For a Unix-syntax file name, just appends a slash.  */)
    (Lisp_Object file)
  {
-- 
2.9.3

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

In GNU Emacs 25.1.1 (x86_64-pc-linux-gnu, GTK+ Version 3.21.5)
  of 2016-09-12 built on calancha-pc
Repository revision: ea0f750e5c1baa21c3ae1b22364662915c2b038f

Re: file-name-as-directory: Update doc. string

[Eli Zaretskii]

> From: Tino Calancha <tino.calancha@gmail.com>
> Date: Mon, 12 Sep 2016 16:04:09 +0900 (JST)
> Cc: tino.calancha@gmail.com
> 
> Doc. string for `file-name-as-directory' is out of date; this
> doc. string suggests that expand-file-name only accepts
> a directory name as its second argument.  It is explicitely
> mentioned in expand-file-name doc. string that the second
> argument can be a directory file name as well.

But that doesn't invalidate what this doc string says, does it?  So
I'm not sure we should remove that sentence.

Thanks.

Re: file-name-as-directory: Update doc. string

[Tino Calancha]

On Mon, 12 Sep 2016, Eli Zaretskii wrote:
> But that doesn't invalidate what this doc string says, does it?  So
> I'm not sure we should remove that sentence.
Yeah, it's a right sentence, but unnecessary: don't bring us any useful
information.  You could also pass FILE, the input of 
`file-name-as-directory',
as second argument to expand-file-name (e-f-n).
When i read this doc, i understand that e-f-n just accepts
directory names as the second arg, which is wrong.  That seems the case at 
the time this sentence was added, but not anymore.

Re: file-name-as-directory: Update doc. string

[Stefan Monnier]

> Yeah, it's a right sentence, but unnecessary: don't bring us any useful
> information.  You could also pass FILE, the input of
> `file-name-as-directory',
> as second argument to expand-file-name (e-f-n).
> When i read this doc, i understand that e-f-n just accepts
> directory names as the second arg, which is wrong.  That seems the case at
> the time this sentence was added, but not anymore.

As a general rule, Emacs doesn't care if a file name has a final slash
or not when the arg is known to be a directory (as is the case for the
second arg of expand-file-name).

There are some exceptions, but these are the ones that need to be
documented LOUDLY (or fixed).


        Stefan