34.6 Obsoleteness

As you add functionality to a package, you may at times want to replace an older function with a new one. To preserve compatibility with existing code, the older function needs to still exist; but users of that function should be told to use the newer one instead. SXEmacs Lisp lets you mark a function or variable as obsolete, and indicate what should be used instead.

Command: make-obsolete function new &optional when

This function indicates that function is an obsolete function, and the function new should be used instead. The byte compiler will issue a warning to this effect when it encounters a usage of the older function, and the help system will also note this in the function’s documentation. new can also be a string (if there is not a single function with the same functionality any more), and should be a descriptive statement, such as "use foo or bar instead" or "this function is unnecessary". If provided, when should be a string indicating when the function was first made obsolete, for example a date or a release number.

Command: make-obsolete-variable variable new

This is like make-obsolete but is for variables instead of functions.

Function: define-obsolete-function-alias oldfun newfun

This function combines make-obsolete and define-function, declaring oldfun to be an obsolete variant of newfun and defining oldfun as an alias for newfun.

Function: define-obsolete-variable-alias oldvar newvar

This is like define-obsolete-function-alias but for variables.

Note that you should not normally put obsoleteness information explicitly in a function or variable’s doc string. The obsoleteness information that you specify using the above functions will be displayed whenever the doc string is displayed, and by adding it explicitly the result is redundancy.

Also, if an obsolete function is substantially the same as a newer one but is not actually an alias, you should consider omitting the doc string entirely (use a null string ‘""’ as the doc string). That way, the user is told about the obsoleteness and is forced to look at the documentation of the new function, making it more likely that he will use the new function.

Function: function-obsoleteness-doc function

If function is obsolete, this function returns a string describing this. This is the message that is printed out during byte compilation or in the function’s documentation. If function is not obsolete, nil is returned.

Function: variable-obsoleteness-doc variable

This is like function-obsoleteness-doc but for variables.

The obsoleteness information is stored internally by putting a property byte-obsolete-info (for functions) or byte-obsolete-variable (for variables) on the symbol that specifies the obsolete function or variable. For more information, see the implementation of make-obsolete and make-obsolete-variable in lisp/bytecomp/bytecomp-runtime.el.