bug#56809: file-name-with-extension: Improve docstring.

[Eli Zaretskii]

> From: Damien Cassou <damien@cassou.me>
> Date: Thu, 28 Jul 2022 08:31:24 +0200
> 
> I found the docstring of file-name-with-extension very confusing so I
> wrote another one.

Thanks.  It definitely needed its wording and its grammar fixed.

I've now fixed that on the emacs-28 release branch.  The modified doc
string says this:

    "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.

  EXTENSION may include the leading dot; if it doesn't, this function
  will provide it.

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

Looks OK?