; Improve documentation of 'file-name-with-extension'

* lisp/files.el (file-name-with-extension): Doc fix.  (Bug#56809)

diff --git a/lisp/files.el b/lisp/files.el
index 1212187274896a91065572aad70fc144cadbbc38..860b9ca7249744e2cbfe8f54079cbb5de95b583a 100644 (file)
--- 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 "[.]")))