From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Luc Teirlinck Newsgroups: gmane.emacs.devel Subject: Documentation of obsolete declarations and aliases. Date: Tue, 3 May 2005 21:30:15 -0500 (CDT) Message-ID: <200505040230.j442UFY20511@raven.dms.auburn.edu> NNTP-Posting-Host: main.gmane.org X-Trace: sea.gmane.org 1115237903 14614 80.91.229.2 (4 May 2005 20:18:23 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 4 May 2005 20:18:23 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed May 04 22:18:21 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1DTQJT-0006a6-VK for ged-emacs-devel@m.gmane.org; Wed, 04 May 2005 22:17:44 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1DTQQq-0005jK-DC for ged-emacs-devel@m.gmane.org; Wed, 04 May 2005 16:25:20 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1DT9rE-0002Jx-Hm for emacs-devel@gnu.org; Tue, 03 May 2005 22:43:28 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1DT9rB-0002IU-VP for emacs-devel@gnu.org; Tue, 03 May 2005 22:43:27 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1DT9qb-0001Tj-2Q for emacs-devel@gnu.org; Tue, 03 May 2005 22:42:49 -0400 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.34) id 1DT9jT-0001Qk-Of for emacs-devel@gnu.org; Tue, 03 May 2005 22:35:28 -0400 Original-Received: from raven.dms.auburn.edu (raven.dms.auburn.edu [131.204.53.29]) by manatee.dms.auburn.edu (8.12.10/8.12.10) with ESMTP id j442UUog008866 for ; Tue, 3 May 2005 21:30:30 -0500 (CDT) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.7p1+Sun/8.11.7) id j442UFY20511; Tue, 3 May 2005 21:30:15 -0500 (CDT) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: emacs-devel@gnu.org X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:36654 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:36654 I propose the following doc changes. The main two points are the following. Firstly, since the Elisp manual describes the details of how to declare variables obsolete, should it not also document how to declare functions obsolete? The patch to lispref/functions.texi does that with a new node "Obsolete Functions". Secondly, all `define-obsolete-variable-alias' and `define-obsolete-function-alias' are is shorthand for two lines of code. But their documentation fails to make that clear and makes them look like a real alternate way to declare variables or functions obsolete. The documentation also fails to point out that the main arguments to these macros need to be quoted (which is somewhat surprising for macros.) I believe that it is better to give a usage example with expansion, as the patches below do, and refer to the docstrings of the two functions they combine for details on those two individual functions. As a minor detail, the section title "Determining whether a function is safe to call" does not appear to follow the usual capitalization conventions. The patch to functions.texi corrects that. As usual, I can install if desired. ===File ~/lispref-functions.texi-diff======================= *** functions.texi 14 Feb 2005 15:39:00 -0600 1.30 --- functions.texi 03 May 2005 19:48:58 -0500 *************** *** 21,26 **** --- 21,27 ---- * Anonymous Functions:: Lambda expressions are functions with no names. * Function Cells:: Accessing or setting the function definition of a symbol. + * Obsolete Functions:: Declaring functions obsolete. * Inline Functions:: Defining functions that the compiler will open code. * Function Safety:: Determining whether a function is safe to call. * Related Topics:: Cross-references to specific Lisp primitives *************** *** 601,607 **** By contrast, in programs that manipulate function definitions for other purposes, it is better to use @code{fset}, which does not keep such ! records. @end defun You cannot create a new primitive function with @code{defun} or --- 602,608 ---- By contrast, in programs that manipulate function definitions for other purposes, it is better to use @code{fset}, which does not keep such ! records. @xref{Function Cells}. @end defun You cannot create a new primitive function with @code{defun} or *************** *** 1150,1155 **** --- 1151,1194 ---- a function defined by another package, it is cleaner to use @code{defadvice} (@pxref{Advising Functions}). + @node Obsolete Functions + @section Declaring Functions Obsolete + + You can use @code{make-obsolete} to declare a function obsolete. This + indicates that the function may be removed at some stage in the future. + + @defun make-obsolete function new &optional when + This function makes the byte compiler warn that the function + @var{function} is obsolete. If @var{new} is a symbol, the warning + message says to use @var{new} instead of @var{function}. @var{new} + does not need to be an alias for @var{function}; it can be a different + function with similar functionality. If @var{new} is a string, it is + the warning message. + + If provided, @var{when} should be a string indicating when the function + was first made obsolete---for example, a date or a release number. + @end defun + + You can define a function as an alias and declare it obsolete at the + same time using the macro @code{define-obsolete-function-alias}. + + @defmac define-obsolete-function-alias function new &optional when docstring + This macro marks the function @var{function} obsolete and also defines + it as an alias for the function @var{new}. A typical call has the form: + + @example + (define-obsolete-function-alias 'old-fun 'new-fun "22.1" "Doc.") + @end example + + @noindent + which is equivalent to the following two lines of code: + + @example + (defalias 'old-fun 'new-fun "Doc.") + (make-obsolete 'old-fun 'new-fun "22.1") + @end example + @end defmac + @node Inline Functions @section Inline Functions @cindex inline functions *************** *** 1186,1192 **** following the definition, just like macros. @node Function Safety ! @section Determining whether a function is safe to call @cindex function safety @cindex safety of functions --- 1225,1231 ---- following the definition, just like macros. @node Function Safety ! @section Determining whether a Function is Safe to Call @cindex function safety @cindex safety of functions ============================================================ ===File ~/lispref-variables.texi-diff======================= *** variables.texi 01 May 2005 21:31:19 -0500 1.58 --- variables.texi 03 May 2005 19:31:47 -0500 *************** *** 1736,1749 **** @defmac define-obsolete-variable-alias variable new &optional when docstring This macro marks the variable @var{variable} as obsolete and also ! makes it an alias for the variable @var{new}. ! If provided, @var{when} should be a string indicating when ! @var{variable} was first made obsolete. The optional argument ! @var{docstring} specifies the documentation string for @var{variable}. ! If @var{docstring} is omitted or nil, @var{variable} uses the ! documentation string of @var{new} unless it already has one of its ! own. @end defmac @defun indirect-variable variable --- 1736,1754 ---- @defmac define-obsolete-variable-alias variable new &optional when docstring This macro marks the variable @var{variable} as obsolete and also ! makes it an alias for the variable @var{new}. A typical call has the form: ! @example ! (define-obsolete-variable-alias 'old-var 'new-var "22.1" "Doc.") ! @end example ! ! @noindent ! which is equivalent to the following two lines of code: ! ! @example ! (defvaralias 'oldvar 'newvar "Doc.") ! (make-obsolete-variable 'old-var 'new-var "22.1") ! @end example @end defmac @defun indirect-variable variable ============================================================ ===File ~/byte-run-diff===================================== *** byte-run.el 26 Apr 2005 09:35:07 -0500 1.10 --- byte-run.el 03 May 2005 19:58:44 -0500 *************** *** 116,127 **** (defmacro define-obsolete-function-alias (function new &optional when docstring) ! "Set FUNCTION's function definition to NEW and warn that FUNCTION is obsolete. ! If provided, WHEN should be a string indicating when FUNCTION was ! first made obsolete, for example a date or a release number. The ! optional argument DOCSTRING specifies the documentation string ! for FUNCTION; if DOCSTRING is omitted or nil, FUNCTION uses the ! documentation string of NEW unluess it already has one." `(progn (defalias ,function ,new ,docstring) (make-obsolete ,function ,new ,when))) --- 116,131 ---- (defmacro define-obsolete-function-alias (function new &optional when docstring) ! "Set FUNCTION's function definition to NEW and mark it obsolete. ! ! \(define-obsolete-function-alias 'old-fun 'new-fun \"22.1\" \"old-fun's doc.\") ! ! is equivalent to the following two lines of code: ! ! \(defalias 'old-fun 'new-fun \"old-fun's doc.\") ! \(make-obsolete 'old-fun 'new-fun \"22.1\") ! ! See the docstrings of `defalias' and `make-obsolete' for more details." `(progn (defalias ,function ,new ,docstring) (make-obsolete ,function ,new ,when))) *************** *** 143,154 **** (defmacro define-obsolete-variable-alias (variable new &optional when docstring) ! "Make VARIABLE a variable alias for NEW and warn that VARIABLE is obsolete. ! If provided, WHEN should be a string indicating when VARIABLE was ! first made obsolete, for example a date or a release number. The ! optional argument DOCSTRING specifies the documentation string ! for VARIABLE; if DOCSTRING is omitted or nil, VARIABLE uses the ! documentation string of NEW unless it already has one." `(progn (defvaralias ,variable ,new ,docstring) (make-obsolete-variable ,variable ,new ,when))) --- 147,163 ---- (defmacro define-obsolete-variable-alias (variable new &optional when docstring) ! "Make VARIABLE a variable alias for NEW and mark it obsolete. ! ! \(define-obsolete-variable-alias 'old-var 'new-var \"22.1\" \"old-var's doc.\") ! ! is equivalent to the following two lines of code: ! ! \(defvaralias 'old-var 'new-var \"old-var's doc.\") ! \(make-obsolete-variable 'old-var 'new-var \"22.1\") ! ! See the docstrings of `defvaralias' and `make-obsolete-variable' or ! Info node `(elisp)Variable Aliases' for more details." `(progn (defvaralias ,variable ,new ,docstring) (make-obsolete-variable ,variable ,new ,when))) ============================================================ ===File ~/eval.c-diff======================================= *** eval.c 28 Apr 2005 07:59:32 -0500 1.236 --- eval.c 03 May 2005 20:44:24 -0500 *************** *** 725,731 **** doc: /* Make SYMBOL a variable alias for symbol ALIASED. Setting the value of SYMBOL will subsequently set the value of ALIASED, and getting the value of SYMBOL will return the value ALIASED has. ! Third arg DOCSTRING, if non-nil, is documentation for SYMBOL. The return value is ALIASED. */) (symbol, aliased, docstring) Lisp_Object symbol, aliased, docstring; --- 725,733 ---- doc: /* Make SYMBOL a variable alias for symbol ALIASED. Setting the value of SYMBOL will subsequently set the value of ALIASED, and getting the value of SYMBOL will return the value ALIASED has. ! Third arg DOCSTRING, if non-nil, is documentation for SYMBOL. If it is ! omitted or nil, SYMBOL gets the documentation string of ALIASED, or of the ! variable at the end of the chain of aliases, if ALIASED is itself an alias. The return value is ALIASED. */) (symbol, aliased, docstring) Lisp_Object symbol, aliased, docstring; ============================================================