Improve documentation of dynamic modules

* src/fns.c (Frequire): Doc fix to include the dynamic module
support.
* src/lread.c (Fload, Vload_suffixes): Doc fixes to include the
dynamic module support.
(Fload): Treat the module suffix the same as '*.el' and '*.elc'
wrt the MUST-SUFFIX argument.

* etc/NEWS: Expand documentation of dynamically loaded modules.

4 files changed, 49 insertions, 20 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 8ed8133beae..dce02c31e59 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -305,13 +305,39 @@ header.
 which specifies an alternative printing method which is faster when
 few or no entries have changed.
 
-** Emacs can now load shared/dynamic libraries (modules) that expose a
-C interface.  Such modules can provide additional functions or
-otherwise interact with Emacs just like Lisp code.  Modules have to
-export a function `emacs_module_init' and conform to the API laid out
-in emacs-module.h.  Modules are disabled by default and need to be
-enabled using the --with-modules configure flag.  They are
-experimental and subject to change.
+** Emacs can now load shared/dynamic libraries (modules).
+A dynamic Emacs module is a shared library that provides additional
+functionality for use in Emacs Lisp programs, just like a package
+written in Emacs Lisp would.  The functions `load' and `require' were
+extended to load such modules, as they do with Emacs Lisp packages.
+
+A module should export a C-callable function named
+`emacs_module_init', which Emacs will call as part of the call to
+`load' or `require' which loads the module.  It should also export a
+symbol named `plugin_is_GPL_compatible' to indicate that its code is
+released under the GPL or compatible license; Emacs will refuse to
+load modules that don't export such a symbol.
+
+If a module needs to call Emacs functions, it should do so through the
+API defined and documented in the header file `emacs-module.h'.  Note
+that any module that provides Lisp-callable functions will have to use
+Emacs functions such as `fset' and `funcall', in order to register its
+functions with the Emacs Lisp interpreter.
+
+Modules can create `user-ptr' Lisp objects that embed pointers to C
+struct's defined by the module.  This is useful for keeping around
+complex data structures created by a module, to be passed back to the
+module's functions.  User-ptr objects can also have associated
+"finalizers" -- functions to be run when the object is GC'ed; this is
+useful for freeing any resources allocated for the underlying data
+structure, such as memory, open file descriptors, etc.  A new
+predicate `user-ptr-p' returns non-nil if its argument is a `usr-ptr'
+object.
+
+Loadable modules in Emacs are an experimental feature, and subject to
+change in future releases.  For that reason, their support is disabled
+by default, and must be enabled by using the `--with-modules' option
+at configure time.
 
 
 * Editing Changes in Emacs 25.1
diff --git a/src/alloc.c b/src/alloc.c
index 53f974533a8..ad3f5235480 100644
--- a/src/alloc.c
+++ b/src/alloc.c
@@ -3712,7 +3712,7 @@ make_event_array (ptrdiff_t nargs, Lisp_Object *args)
 }
 
 #ifdef HAVE_MODULES
-/* Create a new module user ptr object. */
+/* Create a new module user ptr object.  */
 Lisp_Object
 make_user_ptr (void (*finalizer) (void*), void *p)
 {
diff --git a/src/fns.c b/src/fns.c
index 029ac6a83bb..824d96980a0 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -2764,8 +2764,9 @@ DEFUN ("require", Frequire, Srequire, 1, 3, 0,
 If FEATURE is not a member of the list `features', then the feature
 is not loaded; so load the file FILENAME.
 If FILENAME is omitted, the printname of FEATURE is used as the file name,
-and `load' will try to load this name appended with the suffix `.elc' or
-`.el', in that order.  The name without appended suffix will not be used.
+and `load' will try to load this name appended with the suffix `.elc',
+`.el', or the system-dependent suffix for dynamic module files, in that
+order.  The name without appended suffix will not be used.
 See `get-load-suffixes' for the complete list of suffixes.
 If the optional third argument NOERROR is non-nil,
 then return nil if the file is not found instead of signaling an error.
diff --git a/src/lread.c b/src/lread.c
index 43100d9f699..bbff21d01d7 100644
--- a/src/lread.c
+++ b/src/lread.c
@@ -987,7 +987,8 @@ suffix_p (Lisp_Object string, const char *suffix)
 
 DEFUN ("load", Fload, Sload, 1, 5, 0,
        doc: /* Execute a file of Lisp code named FILE.
-First try FILE with `.elc' appended, then try with `.el',
+First try FILE with `.elc' appended, then try with `.el', then try
+with a system-dependent suffix of dynamic modules (see `load-suffixes'),
 then try FILE unmodified (the exact suffixes in the exact order are
 determined by `load-suffixes').  Environment variable references in
 FILE are replaced with their values by calling `substitute-in-file-name'.
@@ -999,10 +1000,10 @@ Print messages at start and end of loading unless
 optional third arg NOMESSAGE is non-nil (but `force-load-messages'
 overrides that).
 If optional fourth arg NOSUFFIX is non-nil, don't try adding
-suffixes `.elc' or `.el' to the specified name FILE.
+suffixes to the specified name FILE.
 If optional fifth arg MUST-SUFFIX is non-nil, insist on
-the suffix `.elc' or `.el'; don't accept just FILE unless
-it ends in one of those suffixes or includes a directory name.
+the suffix `.elc' or `.el' or the module suffix; don't accept just
+FILE unless it ends in one of those suffixes or includes a directory name.
 
 If NOSUFFIX is nil, then if a file could not be found, try looking for
 a different representation of the file by adding non-empty suffixes to
@@ -1084,7 +1085,9 @@ Return t if the file exists and loads successfully.  */)
       if (! NILP (must_suffix))
         {
           /* Don't insist on adding a suffix if FILE already ends with one.  */
-          if (suffix_p (file, ".el") || suffix_p (file, ".elc"))
+          if (suffix_p (file, ".el")
+              || suffix_p (file, ".elc")
+              || suffix_p (file, MODULES_SUFFIX))
             must_suffix = Qnil;
           /* Don't insist on adding a suffix
              if the argument includes a directory name.  */
@@ -1158,9 +1161,7 @@ Return t if the file exists and loads successfully.  */)
 
 #ifdef HAVE_MODULES
   if (suffix_p (found, MODULES_SUFFIX))
-    {
-      return Fmodule_load (found);
-    }
+    return Fmodule_load (found);
 #endif
 
   /* Check if we're stuck in a recursive load cycle.
@@ -4498,10 +4499,11 @@ programs that process this list should tolerate directories both with
 and without trailing slashes.  */);
 
   DEFVAR_LISP ("load-suffixes", Vload_suffixes,
-               doc: /* List of suffixes for (compiled or source) Emacs Lisp files.
+               doc: /* List of suffixes for Emacs Lisp files and dynamic modules.
+This list includes suffixes for both compiled and source Emacs Lisp files.
 This list should not include the empty string.
 `load' and related functions try to append these suffixes, in order,
-to the specified file name if a Lisp suffix is allowed or required.  */);
+to the specified file name if a suffix is allowed or required.  */);
 #ifdef HAVE_MODULES
   Vload_suffixes = list3 (build_pure_c_string (".elc"),
                           build_pure_c_string (".el"),