[Emacs-diffs] emacs-26 3988e93 2/2: Backport: Improve pure and side-effect-free docs

[Basil L. Contovounesios]

branch: emacs-26
commit 3988e93d4b0f2bf677efd9f560373dd526097609
Author: Basil L. Contovounesios <address@hidden>
Commit: Basil L. Contovounesios <address@hidden>

    Backport: 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.
    
    (cherry picked from commit 4430a9b54fca266e48d0eb8b72d83706910f10b8)
---
 doc/lispref/customize.texi |  8 ++++----
 doc/lispref/eval.texi      |  1 +
 doc/lispref/functions.texi |  7 ++++++-
 doc/lispref/internals.texi |  7 +++----
 doc/lispref/symbols.texi   | 15 +++++++++++----
 5 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index f71dedf..02eefe0 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 address@hidden according to
-the argument.  Using a predicate in the list says that objects for which
-the predicate returns address@hidden are acceptable.
+A predicate---that is, a function of one argument that returns either
address@hidden or address@hidden according to the argument.  Using a
+predicate in the list says that objects for which the predicate
+returns address@hidden 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 4bf70d2..73f5396 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -86,6 +86,7 @@ also temporarily alter the environment by binding variables
 (@pxref{Local Variables}).
 
 @cindex side effect
address@hidden 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 d01804e..f641fe7 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
address@hidden 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 38d84f1..62a102e 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -976,10 +976,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
address@hidden so that the compiler optimizer
-knows about it.
+  If you define a function which is side-effect free or pure, give it
+a address@hidden @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 a214a2d..5d71fb3 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
address@hidden @code{pure} property
 If the value is address@hidden, 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 address@hidden, 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
address@hidden @code{side-effect-free} property
 A address@hidden 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
address@hidden, 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 address@hidden, this specifies the named variable's documentation