From 32222fb34cc784f0cfc1716294818fd69233b06c Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 28 Dec 2019 11:13:25 +0200 Subject: [PATCH] Fix documentation of define-obsolete-* functions * doc/lispref/functions.texi (Obsolete Functions): Make documentation of functions that obsolete symbols match the advertised calling conventions. * lisp/emacs-lisp/byte-run.el (define-obsolete-function-alias) (define-obsolete-variable-alias, define-obsolete-face-alias): State in the doc strings that WHEN is a mandatory argument, to be consistent with the advertised calling convention. (Bug#38675) --- doc/lispref/functions.texi | 6 +++--- lisp/emacs-lisp/byte-run.el | 12 ++++++------ 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 6157f9a535b..4307aab9268 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -2090,7 +2090,7 @@ 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. -@defun make-obsolete obsolete-name current-name &optional when +@defun make-obsolete obsolete-name current-name when This function marks @var{obsolete-name} as obsolete. @var{obsolete-name} should be a symbol naming a function or macro, or an alias for a function or macro. @@ -2104,11 +2104,11 @@ should begin in lower case, and end with a period. It can also be @code{nil}, in which case the warning message provides no additional details. -If provided, @var{when} should be a string indicating when the function +The argument @var{when} should be a string indicating when the function was first made obsolete---for example, a date or a release number. @end defun -@defmac define-obsolete-function-alias obsolete-name current-name &optional when doc +@defmac define-obsolete-function-alias obsolete-name current-name when &optional doc This convenience macro marks the function @var{obsolete-name} obsolete and also defines it as an alias for the function @var{current-name}. It is equivalent to the following: diff --git a/lisp/emacs-lisp/byte-run.el b/lisp/emacs-lisp/byte-run.el index 1115c096679..3737473b63b 100644 --- a/lisp/emacs-lisp/byte-run.el +++ b/lisp/emacs-lisp/byte-run.el @@ -378,8 +378,8 @@ 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\") -If provided, WHEN should be a string indicating when the function -was first made obsolete, for example a date or a release number. +WHEN should be a string indicating when the function was first +made obsolete, for example a date or a release number. See the docstrings of `defalias' and `make-obsolete' for more details." (declare (doc-string 4) @@ -423,8 +423,8 @@ dumped with Emacs). This is so that any user customizations are applied before the defcustom tries to initialize the variable (this is due to the way `defvaralias' works). -If provided, WHEN should be a string indicating when the variable -was first made obsolete, for example a date or a release number. +WHEN should be a string indicating when the variable was first +made obsolete, for example a date or a release number. For the benefit of Customize, if OBSOLETE-NAME has any of the following properties, they are copied to @@ -450,8 +450,8 @@ CURRENT-NAME, if it does not already have them: ;; It only really affects M-x describe-face output. (defmacro define-obsolete-face-alias (obsolete-face current-face when) "Make OBSOLETE-FACE a face alias for CURRENT-FACE and mark it obsolete. -If provided, WHEN should be a string indicating when the face -was first made obsolete, for example a date or a release number." +WHEN should be a string indicating when the face was first made +obsolete, for example a date or a release number." `(progn (put ,obsolete-face 'face-alias ,current-face) ;; Used by M-x describe-face. -- 2.39.2