Make cl-declare obsolete

* lisp/emacs-lisp/cl-macs.el (cl-declare): Make obsolete.
* doc/misc/cl.texi (Declarations): Don't document above obsolete
macro.  (Bug#63288)

3 files changed, 9 insertions, 29 deletions

diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 8fb308e64a5..862b8f4a1c4 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -60,7 +60,7 @@ modify this GNU manual.''
 * Predicates::           Type predicates and equality predicates.
 * Control Structure::    Assignment, conditionals, blocks, looping.
 * Macros::               Destructuring, compiler macros.
-* Declarations::         @code{cl-proclaim}, @code{cl-declare}, etc.
+* Declarations::         @code{cl-proclaim}, @code{cl-declaim}, etc.
 * Symbols::              Property lists, creating symbols.
 * Numbers::              Predicates, functions, random numbers.
 * Sequences::            Mapping, functions, searching, sorting.
@@ -2652,8 +2652,7 @@ mechanism that allows you to give the compiler special hints
 about the types of data that will be stored in particular variables,
 and about the ways those variables and functions will be used.  This
 package defines versions of all the Common Lisp declaration forms:
-@code{declare}, @code{locally}, @code{proclaim}, @code{declaim},
-and @code{the}.
+@code{proclaim}, @code{declaim}, and @code{the}.
 
 Most of the Common Lisp declarations are not currently useful in Emacs
 Lisp.  For example, the byte-code system provides little
@@ -2683,15 +2682,6 @@ compiler treats the rest of the file that contains the @code{cl-declaim}
 form.)
 @end defmac
 
-@defmac cl-declare decl-specs@dots{}
-This macro is used to make declarations within functions and other
-code.  Common Lisp allows declarations in various locations, generally
-at the beginning of any of the many ``implicit @code{progn}s''
-throughout Lisp syntax, such as function bodies, @code{let} bodies,
-etc.  Currently the only declaration understood by @code{cl-declare}
-is @code{special}.
-@end defmac
-
 @defmac cl-the type form
 @code{cl-the} returns the value of @code{form}, first checking (if
 optimization settings permit) that it is of type @code{type}.  Future
@@ -2707,8 +2697,8 @@ For now, Emacs Lisp will treat the above code as exactly equivalent
 to @code{(mapcar 'car foo)}.
 @end defmac
 
-Each @var{decl-spec} in a @code{cl-proclaim}, @code{cl-declaim}, or
-@code{cl-declare} should be a list beginning with a symbol that says
+Each @var{decl-spec} in a @code{cl-proclaim} or @code{cl-declaim}
+should be a list beginning with a symbol that says
 what kind of declaration it is.  This package currently understands
 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
 and @code{warn} declarations.  (The @code{warn} declaration is an
@@ -2726,9 +2716,6 @@ bound in the body of the function.  The compiler normally emits
 warnings for such references, since they could be typographical
 errors for references to local variables.
 
-The declaration @code{(cl-declare (special @var{var1} @var{var2}))} is
-equivalent to @code{(defvar @var{var1}) (defvar @var{var2})}.
-
 In top-level contexts, it is generally better to write
 @code{(defvar @var{var})} than @code{(cl-declaim (special @var{var}))},
 since @code{defvar} makes your intentions clearer.
@@ -2760,12 +2747,6 @@ request that a function you have defined should be inlined,
 but it is impolite to use it to request inlining of an external
 function.
 
-In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
-before a particular call to a function to cause just that call to
-be inlined; the current byte compilers provide no way to implement
-this, so @code{(cl-declare (inline @dots{}))} is currently ignored by
-this package.
-
 @item notinline
 The @code{notinline} declaration lists functions which should
 not be inlined after all; it cancels a previous @code{inline}
@@ -2800,12 +2781,7 @@ Emacs itself, Emacs will not crash with a segmentation fault
 just because of an error in a fully-optimized Lisp program.
 
 The @code{optimize} declaration is normally used in a top-level
-@code{cl-proclaim} or @code{cl-declaim} in a file; Common Lisp allows
-it to be used with @code{declare} to set the level of optimization
-locally for a given form, but this will not work correctly with the
-current byte-compiler.  (The @code{cl-declare}
-will set the new optimization level, but that level will not
-automatically be unset after the enclosing form is done.)
+@code{cl-proclaim} or @code{cl-declaim} in a file.
 
 @item warn
 This declaration controls what sorts of warnings are generated
diff --git a/etc/NEWS b/etc/NEWS
index 4c0cff8ac7c..763ff2206ac 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -537,6 +537,9 @@ Such bindings make it possible to compute which function to bind to FUNC.
 *** 'cl-locally' is now obsolete.
 It is an alias for the 'progn' special-form.
 
++++
+*** 'cl-declare' is now obsolete; use 'defvar' instead.
+
 ** Whitespace
 
 ---
diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index 1578603cedd..dbaa0d9bcb8 100644
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -2728,6 +2728,7 @@ For instance
 
 will turn off byte-compile warnings in the function.
 See Info node `(cl)Declarations' for details."
+  (declare (obsolete defvar "31.1"))
   (if (macroexp-compiling-p)
       (while specs
         (if (listp cl--declare-stack) (push (car specs) cl--declare-stack))