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)

1 files changed, 8 insertions, 0 deletions

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 78372a8a10e..86181f1b491 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