defcustom :type (file :must-match t)

[Drew Adams]

I don't understand the customization type `(file :must-match t)'. The Elisp
manual says only this: "The value must be a file name for an existing file,
and you can do completion with `M-<TAB>'."

I don't see where/when/how this existence criterion is enforced.  At what
point is it checked and an error raised if you try to use a name that
corresponds to no file?

I am able to create a defcustom with a file name (with complete path) that
does not correspond to an existing file. I am able to customize the file
name in Customize, providing a name that doesn't correspond to an existing
file. I am able to set for the current session and even save such a nonsense
value.

So, in what sense _must_ the file-name value be the name of an existing
file? What am I missing?

The last phrase is, in any case, unclear: "and you can do completion with
`M-<TAB>'"? When/where can you do this? Does this mean in Customize, when
"you" are typing a new file name? With `set-variable' also? When "you" are
typing the defcustom? The Elisp manual is for programmers, and this section
of the manual tells "you" how to define a file-name :type, so I would guess
that the "you" here is not an end user of Customize but a programmer writing
a defcustom. But trial and error shows that "you" is the Customize end user,
and only Customize is meant, not also `set-variable'. This should be cleared
up.

If the only "must" check for existence is that provided by file-name
completion (e.g. REQUIRE-MATCH arg to `completing-read'), then this whole
entry should be rewritten to say that. Currently, it gives the impression
that `:type (file :must-match t)' will somehow, somewhere, somewhen, force
users to use file names that correspond to existing files.