Improve documentation of 'emacs_function' in modules

* doc/lispref/internals.texi (Module Functions): Warn about
accessing the ARGS array in module functions.

(cherry picked from commit c494a6e879dfeecb0cec3e9ae7bc0d3c682a9185)

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index ee3463a1fd64d7bcf1f533b49d55ba3f804fd3d6..a5480a9bf8aa8dc09f281e8d61d00489869e64ce 100644 (file)
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -1374,6 +1374,15 @@ objects between Emacs and the module (@pxref{Module Values}).  The
 provides facilities for conversion between basic C data types and the
 corresponding @code{emacs_value} objects.
 
+In the module function's body, do @emph{not} attempt to access
+elements of the @var{args} array beyond the index
+@code{@var{nargs}-1}: memory for the @var{args} array is allocated
+exactly to accommodate @var{nargs} values, and accessing beyond that
+will most probably crash your module.  In particular, if the value of
+@var{nargs} passed to the function at run time is zero, it must not
+access @var{args} at all, as no memory will have been allocated for it
+in that case.
+
 A module function always returns a value.  If the function returns
 normally, the Lisp code which called it will see the Lisp object
 corresponding to the @code{emacs_value} value the function returned.