bug#45437: 27.1; make-temp-file parameter change in emacs 26 missing in documentation

bug#45437: 27.1; make-temp-file parameter change in emacs 26 missing in documentation

[Hendrik Tews]

Hi,

the function make-temp-file was extended in emacs 26 with the
additional optional TEXT argument. However, describe-function
says "Probably introduced at or before Emacs version 21.1.",
leaving the impression that one can safely use the TEXT argument
if one wants to write backward compatible code.

Please amend the documentation of make-temp-file to mention that
the TEXT argument was added in emacs 26. Without such
information, it is very difficult to write code that works in a
variety of emacs major versions.

Thanks,

Hendrik

bug#45437: 27.1; make-temp-file parameter change in emacs 26 missing in documentation

[Lars Ingebrigtsen]

Hendrik Tews <hendrik@askra.de> writes:

> the function make-temp-file was extended in emacs 26 with the
> additional optional TEXT argument. However, describe-function
> says "Probably introduced at or before Emacs version 21.1.",
> leaving the impression that one can safely use the TEXT argument
> if one wants to write backward compatible code.

The "probably" only talks about the function itself; not about the
parameters.

> Please amend the documentation of make-temp-file to mention that
> the TEXT argument was added in emacs 26. Without such
> information, it is very difficult to write code that works in a
> variety of emacs major versions.

Sorry; we don't keep track of added parameters in a systematic way, so
that would be unfeasible.  You have to read the NEWS file to determine
this stuff (or use the VC functions, of you have a checked-out Emacs).

Closing.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#45437: 27.1; make-temp-file parameter change in emacs 26 missing in documentation

[Basil L. Contovounesios]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Hendrik Tews <hendrik@askra.de> writes:
>
>> the function make-temp-file was extended in emacs 26 with the
>> additional optional TEXT argument. However, describe-function
>> says "Probably introduced at or before Emacs version 21.1.",
>> leaving the impression that one can safely use the TEXT argument
>> if one wants to write backward compatible code.
>
> The "probably" only talks about the function itself; not about the
> parameters.

And is an imperfect heuristic based on searching NEWS files, hence
"probably".

>> Please amend the documentation of make-temp-file to mention that
>> the TEXT argument was added in emacs 26. Without such
>> information, it is very difficult to write code that works in a
>> variety of emacs major versions.
>
> Sorry; we don't keep track of added parameters in a systematic way, so
> that would be unfeasible.  You have to read the NEWS file to determine
> this stuff (or use the VC functions, of you have a checked-out Emacs).

See also: https://lists.gnu.org/r/emacs-devel/2020-12/msg00371.html

-- 
Basil