bug#47762: Doc of `macroexp-file-name' (Emacs 28)

bug#47762: Doc of `macroexp-file-name' (Emacs 28)

[Drew Adams]

I don't have Emacs 28 code, where this function is apparently defined.
I'm going by what is shown here:

https://emacs.stackexchange.com/a/64404/105

The doc string shown there is this:

 Return the name of the file from which the code comes.
 Returns nil when we do not know.
 A non-nil result is expected to be reliable when called from a macro in order
 to find the file in which the macro's call was found, and it should be
 reliable as well when used at the top-level of a file.
 Other uses risk returning non-nil value that point to the wrong file.

Please consider clarifying the doc for this function.  For example, just
what code is meant here: "the file from which the code comes"?
                                              ^^^^^^^^

Looking at the source code doesn't help understanding of the function
either (at least in releases prior to Emacs 28).  The doc string for
variable `current-load-file' just says "Used for internal purposes by
`load'.", and there's no doc string at all for variable
`byte-compile-current-file'.

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.19041
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#47762: Doc of `macroexp-file-name' (Emacs 28)

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Tue, 13 Apr 2021 22:34:57 +0000
> 
> The doc string shown there is this:
> 
>  Return the name of the file from which the code comes.
>  Returns nil when we do not know.
>  A non-nil result is expected to be reliable when called from a macro in order
>  to find the file in which the macro's call was found, and it should be
>  reliable as well when used at the top-level of a file.
>  Other uses risk returning non-nil value that point to the wrong file.
> 
> Please consider clarifying the doc for this function.  For example, just
> what code is meant here: "the file from which the code comes"?
>                                               ^^^^^^^^

This is explained by the text that you cited.

Closing.

bug#47762: [External] : Re: bug#47762: Doc of `macroexp-file-name' (Emacs 28)

[Drew Adams]

> > The doc string shown there is this:
> >
> >  Return the name of the file from which the code comes.
> >  Returns nil when we do not know.
> >  A non-nil result is expected to be reliable when called from a macro in
> order
> >  to find the file in which the macro's call was found, and it should be
> >  reliable as well when used at the top-level of a file.
> >  Other uses risk returning non-nil value that point to the wrong file.
> >
> > Please consider clarifying the doc for this function.  For example, just
> > what code is meant here: "the file from which the code comes"?
> >                                               ^^^^^^^^
> 
> This is explained by the text that you cited.
> Closing.

FWIW, I disagree completely.  A reader really has
no idea how or where to use this function.