[Emacs-diffs] emacs-26 f4c9894: Improve documentation of actual arglist

[Eli Zaretskii]

branch: emacs-26
commit f4c989427b5fa0bb8507d14850fcbc35ff159e95
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of actual arglist
    
    * doc/lispref/functions.texi (Function Documentation): Advise
    against using '(fn ARGLIST)' method of advertising a calling
    convention when the old calling convention is deprecated.
    (Bug#31191)
---
 doc/lispref/functions.texi | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 78372a8..86181f1 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -498,6 +498,14 @@ derived from the actual arguments of the function.
 arguments written in a macro definition often do not correspond to the
 way users think of the parts of the macro call.
 
+  Do not use this feature if you want to deprecate the calling
+convention and favor the one you advertise by the above specification.
+Instead, use the @code{advertised-calling-convention} declaration
+(@pxref{Declare Form}) or @code{set-advertised-calling-convention}
+(@pxref{Obsolete Functions}), because these two will cause the byte
+compiler emit a warning message when it compiles Lisp programs which
+use the deprecated calling convention.
+
 @node Function Names
 @section Naming a Function
 @cindex function definition