Re: Adding support for xref jumping to headers/interfaces

[Dmitry Gutov <dmitry@gutov.dev>]

On 28/11/2023 11:51, João Távora wrote:
>> I'm wary of using macros as framework/library interface in Elisp because
>> unless they are very stable, they can cause versioning problems when
>> upgrading or reverting to an earlier version. You change a macro, but a
>> dependent package is already installed and byte-compiled, and there
>> won't be a recompilation until its next update. We might not even intend
>> to change them much, but then you don't always anticipate a bugfix.
> BTW, these tangents and distractions are possibly what Eli complained
> about when trying to follow this discussion about xref, but in the
> interest of Lisp programmers out there, what you describe is both a
> very real problem and a problem which is trivial to eradicate.   Just
> expand to functions.  Here's a general form of a command-defining macro
> suitable for a library interface.
> 
> (defmacro mylib-define-command (name &rest margs)
>     `(defun ,name (&rest args)
>         (interactive (mylib--interactive ,@margs))
>         (apply #'mylib--doit args)))
> 
> Then you can freely change the implementations of mylib--interactive
> and mylib--doit in mylib.el.
> 
> And there are tricks to concoct the docstring at
> consultation time too (see 13.2.4 Documentation Strings of Functions)

That's a good practice, and it works (and mitigates the issues) until we 
need to change the underlying function, for some reasons or other. In 
that sense, having the expansion use private functions (with "--" in the 
name) doesn't do much because those cannot be safely renamed, extended, 
etc. Unlike when they're called by a public function.

Anyway, adding such macro is even less of a priority concern than the 
addition (or not) of new key bindings. We could always do it later.