emacs-29 a0b273ef300: ; Clarify documentation of 'file-modes-number-to-symbolic'

[Eli Zaretskii]

branch: emacs-29
commit a0b273ef300adabac0cb656fcc3657ebaf6ed528
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Clarify documentation of 'file-modes-number-to-symbolic'
    
    * doc/lispref/files.texi (Changing Files):
    * lisp/files.el (file-modes-number-to-symbolic): Clarify the
    confusion with "symbolic" forms of file modes.  (Bug#61709)
---
 doc/lispref/files.texi |  6 +++++-
 lisp/files.el          | 11 +++++++----
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 5062b1697b5..f8781d4895b 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1985,7 +1985,11 @@ all.
 
 @defun file-modes-number-to-symbolic modes
 This function converts a numeric file mode specification in
-@var{modes} into the equivalent symbolic form.
+@var{modes} into the equivalent string form.  The string which this
+function returns is in the same format produced by the shell command
+@kbd{ls -l} and by @code{file-attributes}, @emph{not} the symbolic
+form accepted by @code{file-modes-symbolic-to-number} and the
+@command{chmod} shell command.
 @end defun
 
 @defun set-file-times filename &optional time flag
diff --git a/lisp/files.el b/lisp/files.el
index 57e01340359..db3f348c4b5 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -8391,11 +8391,14 @@ as in \"og+rX-w\"."
     num-rights))
 
 (defun file-modes-number-to-symbolic (mode &optional filetype)
-  "Return a string describing a file's MODE.
+  "Return a description of a file's MODE as a string of 10 letters and dashes.
+The returned string is like the mode description produced by \"ls -l\".
 For instance, if MODE is #o700, then it produces `-rwx------'.
-FILETYPE if provided should be a character denoting the type of file,
-such as `?d' for a directory, or `?l' for a symbolic link and will override
-the leading `-' char."
+Note that this is NOT the same as the \"chmod\" style symbolic description
+accepted by `file-modes-symbolic-to-number'.
+FILETYPE, if provided, should be a character denoting the type of file,
+such as `?d' for a directory, or `?l' for a symbolic link, and will override
+the leading `-' character."
   (string
    (or filetype
        (pcase (ash mode -12)