bug#66554: [PATCH] Add the public API of Compat to the core

[Daniel Mendler]

Philip Kaludercic <philipk@posteo.net> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> Eli Zaretskii <eliz@gnu.org> writes:
>>
>>>> From: Philip Kaludercic <philipk@posteo.net>
>>>> Cc: mail@daniel-mendler.de,  66554@debbugs.gnu.org,  
>>>> stefankangas@gmail.com,
>>>>   monnier@iro.umontreal.ca
>>>> Date: Tue, 06 Feb 2024 19:10:32 +0000
>>>> 
>>>> >> +@defmac compat-call fun &rest args
>>>> >> +This macro calls the compatibility function @var{fun} with @var{args}.
>>>> >> +Many functions provided by Compat can be called directly without this
>>>> >> +macro.  However in the case where Compat provides an alternative
>>>> >> +version of an existing function, the function call has to go through
>>>> >> +@code{compat-call}.
>>>> >> +@end defmac
>>>> >
>>>> > This description left me without understanding when I need to use
>>>> > compat-call and when I can just call FUN.  Can you explain more?
>>>> 
>>>> The intention was for this paragraph to catch that case,
>>>> 
>>>>   However in the case where Compat provides an alternative version of an
>>>>   existing function, the function call has to go through
>>>>   @code{compat-call}.
>>>> 
>>>> though the real information is to be found in the Compat manual, where
>>>> the functions that have to be called via compat-call are documented.
>>>> 
>>>> Should the above sentence be rephrased to give a general feeling for
>>>> when this is the case
>>>> 
>>>>   However in the case where Compat provides an alternative version of an
>>>>   existing function, the function call has to go through
>>>>   @code{compat-call}.  This is the case when, for example the signature
>>>>   changes between versions, preventing older versions of Emacs from
>>>>   using optional arguments introduced in newer releases.
>>>> 
>>>> or should we just refer to the external manual?
>>>
>>> Let me try to make my point more clear: I'd prefer that the reader
>>> emerges from reading this description with a practical way of knowing
>>> when to call the function directly and when to call it via
>>> 'compat-call'.  If that's not easy to understand, perhaps we should
>>> tell that 'compat-call' should always be used, to avoid some rare
>>> corner cases where a direct call will not do, and be done?
>>
>> I don't think we should recommend always using `compat-call', that would
>> make code unreadable.  What definitions have to be called via
>> `compat-call' really depends on how they were defined in Compat.  I
>> don't know of a better rule to describe it without copying the
>> documentation from the Compat manual (that wouldn't be a good idea
>> either, because it wouldn't stay up to date).
>
> Daniel, do have any ideas how to improve the documentation here?  It
> seems to me that the authoritative source of information on what
> functions to compat-call is Compat itself, right?

The Compat manual explicitly lists how each function should be called.
This information is not static, since new functions are added with every
Compat release. Examples from the Compat manual:

   Function: compat-call plist-get plist prop &optional predicate
   Function: ntake n list

I think we should explain the general idea in the compat.el file in
Emacs itself (docstrings and commentary) and refer to the Compat manual
for the list of supported functions and their calling convention. The
explanations in the current patch look good to me.

Daniel