Improve pure and side-effect-free docs

For discussion, see thread starting at:
https://lists.gnu.org/archive/html/emacs-devel/2019-04/msg00316.html
* doc/lispref/customize.texi (Composite Types): Do not overspecify
:match-alternatives predicates.
* doc/lispref/eval.texi (Intro Eval): Anchor definition of "side
effect" for cross-referencing...
* doc/lispref/functions.texi (What Is a Function): ...from here.
Define what a pure function is.
* doc/lispref/internals.texi (Writing Emacs Primitives): Describe
currently preferred approach to marking primitives as pure and
side-effect-free.
* doc/lispref/symbols.texi (Standard Properties): Expand description
of pure and side-effect-free properties.

5 files changed, 25 insertions, 13 deletions

diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index f71dedfd8b0..02eefe0f585 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -950,10 +950,10 @@ possibilities:
 
 @itemize @bullet
 @item
-A predicate---that is, a function of one argument that has no side
-effects, and returns either @code{nil} or non-@code{nil} according to
-the argument.  Using a predicate in the list says that objects for which
-the predicate returns non-@code{nil} are acceptable.
+A predicate---that is, a function of one argument that returns either
+@code{nil} or non-@code{nil} according to the argument.  Using a
+predicate in the list says that objects for which the predicate
+returns non-@code{nil} are acceptable.
 
 @item
 A quoted constant---that is, @code{'@var{object}}.  This sort of element
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index db42dfb6373..39c5a1ec506 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -87,6 +87,7 @@ also temporarily alter the environment by binding variables
 (@pxref{Local Variables}).
 
 @cindex side effect
+@anchor{Definition of side effect}
   Evaluating a form may also make changes that persist; these changes
 are called @dfn{side effects}.  An example of a form that produces a
 side effect is @code{(setq foo 1)}.
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 222f863c988..97f7fb9f79e 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -38,11 +38,16 @@ define them.
 @cindex return value
 @cindex value of function
 @cindex argument
+@cindex pure function
   In a general sense, a function is a rule for carrying out a
 computation given input values called @dfn{arguments}.  The result of
 the computation is called the @dfn{value} or @dfn{return value} of the
 function.  The computation can also have side effects, such as lasting
-changes in the values of variables or the contents of data structures.
+changes in the values of variables or the contents of data structures
+(@pxref{Definition of side effect}).  A @dfn{pure function} is a
+function which, in addition to having no side effects, always returns
+the same value for the same combination of arguments, regardless of
+external factors such as machine type or system state.
 
   In most computer languages, every function has a name.  But in Lisp,
 a function in the strictest sense has no name: it is an object which
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index fc5ce594e61..25892d4b57c 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -1031,10 +1031,9 @@ number of arguments.  They work by calling @code{Ffuncall}.
 @file{lisp.h} contains the definitions for some important macros and
 functions.
 
-  If you define a function which is side-effect free, update the code
-in @file{byte-opt.el} that binds @code{side-effect-free-fns} and
-@code{side-effect-and-error-free-fns} so that the compiler optimizer
-knows about it.
+  If you define a function which is side-effect free or pure, give it
+a non-@code{nil} @code{side-effect-free} or @code{pure} property,
+respectively (@pxref{Standard Properties}).
 
 @node Writing Dynamic Modules
 @section Writing Dynamically-Loaded Modules
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index a214a2d3fd8..5d71fb39a25 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -558,9 +558,12 @@ deleted from the local value of a hook variable when changing major
 modes.  @xref{Setting Hooks}.
 
 @item pure
+@cindex @code{pure} property
 If the value is non-@code{nil}, the named function is considered to be
-side-effect free.  Calls with constant arguments can be evaluated at
-compile time.  This may shift run time errors to compile time.
+pure (@pxref{What Is a Function}).  Calls with constant arguments can
+be evaluated at compile time.  This may shift run time errors to
+compile time.  Not to be confused with pure storage (@pxref{Pure
+Storage}).
 
 @item risky-local-variable
 If the value is non-@code{nil}, the named variable is considered risky
@@ -579,9 +582,13 @@ The value specifies a function for determining safe file-local values
 for the named variable.  @xref{File Local Variables}.
 
 @item side-effect-free
+@cindex @code{side-effect-free} property
 A non-@code{nil} value indicates that the named function is free of
-side-effects, for determining function safety (@pxref{Function
-Safety}) as well as for byte compiler optimizations.  Do not set it.
+side effects (@pxref{What Is a Function}), so the byte compiler may
+ignore a call whose value is unused.  If the property's value is
+@code{error-free}, the byte compiler may even delete such unused
+calls.  In addition to byte compiler optimizations, this property is
+also used for determining function safety (@pxref{Function Safety}).
 
 @item variable-documentation
 If non-@code{nil}, this specifies the named variable's documentation