master 291763feca3: Improve documentation of 'require-with-check'

[Eli Zaretskii]

branch: master
commit 291763feca34174290345055a6748436839f7606
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    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'.
---
 doc/lispref/loading.texi | 13 +++++++++++++
 etc/NEWS                 |  4 ++++
 2 files changed, 17 insertions(+)

diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 125011c780f..d35800fb4e0 100644
--- 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 f60f3f04158..a174cf52d50 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1361,7 +1361,11 @@ values.
 
 * 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'.