emacs-28 23112f89f9: ; Improve documentation of 'file-name-with-extension'

[Eli Zaretskii]

branch: emacs-28
commit 23112f89f9c0a253a6f30e566d7e4b4e3a3fe8ca
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Improve documentation of 'file-name-with-extension'
    
    * lisp/files.el (file-name-with-extension): Doc fix.  (Bug#56809)
---
 lisp/files.el | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/lisp/files.el b/lisp/files.el
index 1212187274..860b9ca724 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -5033,14 +5033,16 @@ extension, the value is \"\"."
             "")))))
 
 (defun file-name-with-extension (filename extension)
-  "Set the EXTENSION of a FILENAME.
+  "Return FILENAME modified to have the specified EXTENSION.
 The extension (in a file name) is the part that begins with the last \".\".
+This function removes any existing extension from FILENAME, and then
+appends EXTENSION to it.
 
-Trims a leading dot from the EXTENSION so that either \"foo\" or
-\".foo\" can be given.
+EXTENSION may include the leading dot; if it doesn't, this function
+will provide it.
 
-Errors if the FILENAME or EXTENSION are empty, or if the given
-FILENAME has the format of a directory.
+It is an error if FILENAME or EXTENSION is empty, or if FILENAME
+is in the form of a directory name according to `directory-name-p'.
 
 See also `file-name-sans-extension'."
   (let ((extn (string-trim-left extension "[.]")))