Improve documentation of 'require-with-check'

* doc/lispref/loading.texi (Named Features): Document
'require-with-check'.

* etc/NEWS: Fix wording of entry about 'require-with-check'.

diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 125011c780f87105635d6758249c4d0f7197b5c3..d35800fb4e0f038f1442b5026b52de542ed9eb1c 100644 (file)
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -1011,6 +1011,19 @@ If loading the file succeeds but does not provide @var{feature},
 @code{require} signals an error about the missing feature.
 @end defun
 
+@defun require-with-check feature &optional filename noerror
+This function works like @code{require}, except if @var{feature} is
+already loaded (i.e.@: is already a member of the list in
+@code{features}, see below).  If @var{feature} is already loaded, this
+function checks if @var{feature} was provided by a file different from
+@var{filename}, and if so, it by default signals an error.  If the
+value of the optional argument @var{noerror} is @code{reload}, the
+function doesn't signal an error, but instead forcibly reloads
+@var{filename}; if @var{noerror} is some other non-@code{nil} value,
+the function emits a warning about @var{feature} being already
+provided by another file.
+@end defun
+
 @defun featurep feature &optional subfeature
 This function returns @code{t} if @var{feature} has been provided in
 the current Emacs session (i.e., if @var{feature} is a member of

diff --git a/etc/NEWS b/etc/NEWS
index f60f3f04158ed6593747c466b305058fc7f8de26..a174cf52d5088545a2d57b623d2fa35f3fbac382 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1361,7 +1361,11 @@ values.
 \f
 * Lisp Changes in Emacs 30.1
 
++++
 ** New function 'require-with-check' to detect new versions shadowing.
+This is like 'require', but it checks whether the argument 'feature'
+is already loaded, in which case it either signals an error or
+forcibly reloads the file that defines the feature.
 
 +++
 ** New 'pop-up-frames' action alist entry for 'display-buffer'.