Subject: Re: bug#78995: [PATCH] ;;;autoload-expand for special macros

From: Eli Zaretskii <[email-masked]>
Date: Mon, 04 Aug 2025 15:51:47 +0300

> From: "J.D. Smith" <[email-masked]>
> Cc: [email-masked],  [email-masked],  [email-masked]
> Date: Sun, 03 Aug 2025 18:53:34 -0400
> 
> > No, I mean _why_ we want to request that in those places and not the
> > others.
> 
> The short but unsatisfying answer is to preserve the hard-coded list of
> macros to expand, which this functionality replaces and extends.  The
> former explanation in `loaddefs-generate--make-autoload' was quite
> terse:
> 
>  ;; For complex cases, try again on the macro-expansion.
> 
> I've tried to inject a short explanation everywhere this declaration is
> used.  I left the `byte-run--set-autoload-macro' alone, since that's
> just a generic property setter, and values other than `expand' may be
> used in the future. Latest patch below.

This is much better (thanks!), but I think we need to improve it some
more by saying in the manual that this declaration is an alternative
to hard-coding macros in loaddefs--defining-macros in loaddefs-gen.el.

> +the final form (@code{(put my-mode 'hidden-prop nil)}) will not be

Long forms like the above should be wrapped in @w{..}, to prevent them
from being broken between two lines.

> +copied into the autoload file.

"autoloads file", I guess?

> +Note that, if a symbol in the @code{car} of an autoloaded form is found
> +to be undefined during autoload generation, the file in which the
> +associated @samp{;;;###autoload} appears will itself be loaded, to give
> +the macro a chance to be defined.  Packages which use special loading
> +mechanisms, including loading their own @samp{foo-autoload.el} file,

"foo" should be in @var, since it isn't a literal "foo".  I'd even use
@file{@var{package}-loaddefs.el} instead (note the use of @file).

> +;; The following macros are known to define functions, and are treated
> +;; specially when encountered during autoload generation, translating
> +;; calls to them into appropriate (autoload function ...) forms.
> +;; TODO: some macros can be removed from this list once they
> +;;  (declare ((autoload-macro expand) ...)

I'd prefer to say explicitly that autoload-macro is the alternative
used so as to keep this list as short as possible.

Thanks.