From: Eli Zaretskii <eliz@gnu.org>
Date: Thu, 19 Apr 2018 08:29:50 +0000 (+0300)
Subject: Improve documentation of actual arglist
X-Git-Tag: emacs-26.1~66
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=f4c989427b5fa0bb8507d14850fcbc35ff159e95;p=emacs.git

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)
---

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