diff options
Diffstat (limited to 'devdocs/elisp/obsolete-functions.html')
| -rw-r--r-- | devdocs/elisp/obsolete-functions.html | 24 |
1 files changed, 24 insertions, 0 deletions
diff --git a/devdocs/elisp/obsolete-functions.html b/devdocs/elisp/obsolete-functions.html new file mode 100644 index 00000000..6257bf3e --- /dev/null +++ b/devdocs/elisp/obsolete-functions.html @@ -0,0 +1,24 @@ + <h3 class="section">Declaring Functions Obsolete</h3> <p>You can mark a named function as <em>obsolete</em>, meaning that it may be removed at some point in the future. This causes Emacs to warn that the function is obsolete whenever it byte-compiles code containing that function, and whenever it displays the documentation for that function. In all other respects, an obsolete function behaves like any other function. </p> <p>The easiest way to mark a function as obsolete is to put a <code>(declare (obsolete …))</code> form in the function’s <code>defun</code> definition. See <a href="declare-form">Declare Form</a>. Alternatively, you can use the <code>make-obsolete</code> function, described below. </p> <p>A macro (see <a href="macros">Macros</a>) can also be marked obsolete with <code>make-obsolete</code>; this has the same effects as for a function. An alias for a function or macro can also be marked as obsolete; this makes the alias itself obsolete, not the function or macro which it resolves to. </p> <dl> <dt id="make-obsolete">Function: <strong>make-obsolete</strong> <em>obsolete-name current-name when</em> +</dt> <dd> +<p>This function marks <var>obsolete-name</var> as obsolete. <var>obsolete-name</var> should be a symbol naming a function or macro, or an alias for a function or macro. </p> <p>If <var>current-name</var> is a symbol, the warning message says to use <var>current-name</var> instead of <var>obsolete-name</var>. <var>current-name</var> does not need to be an alias for <var>obsolete-name</var>; it can be a different function with similar functionality. <var>current-name</var> can also be a string, which serves as the warning message. The message should begin in lower case, and end with a period. It can also be <code>nil</code>, in which case the warning message provides no additional details. </p> <p>The argument <var>when</var> should be a string indicating when the function was first made obsolete—for example, a date or a release number. </p> +</dd> +</dl> <dl> <dt id="define-obsolete-function-alias">Macro: <strong>define-obsolete-function-alias</strong> <em>obsolete-name current-name when &optional doc</em> +</dt> <dd> +<p>This convenience macro marks the function <var>obsolete-name</var> obsolete and also defines it as an alias for the function <var>current-name</var>. It is equivalent to the following: </p> <div class="example"> <pre class="example">(defalias <var>obsolete-name</var> <var>current-name</var> <var>doc</var>) +(make-obsolete <var>obsolete-name</var> <var>current-name</var> <var>when</var>) +</pre> +</div> </dd> +</dl> <p>In addition, you can mark a particular calling convention for a function as obsolete: </p> <dl> <dt id="set-advertised-calling-convention">Function: <strong>set-advertised-calling-convention</strong> <em>function signature when</em> +</dt> <dd> +<p>This function specifies the argument list <var>signature</var> as the correct way to call <var>function</var>. This causes the Emacs byte compiler to issue a warning whenever it comes across an Emacs Lisp program that calls <var>function</var> any other way (however, it will still allow the code to be byte compiled). <var>when</var> should be a string indicating when the variable was first made obsolete (usually a version number string). </p> <p>For instance, in old versions of Emacs the <code>sit-for</code> function accepted three arguments, like this </p> <div class="example"> <pre class="example"> (sit-for seconds milliseconds nodisp) +</pre> +</div> <p>However, calling <code>sit-for</code> this way is considered obsolete (see <a href="waiting">Waiting</a>). The old calling convention is deprecated like this: </p> <div class="example"> <pre class="example">(set-advertised-calling-convention + 'sit-for '(seconds &optional nodisp) "22.1") +</pre> +</div> </dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Obsolete-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Obsolete-Functions.html</a> + </p> +</div> |