From 7bbcfcfc201d8a924b9f19abcc9307001b79ec86 Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" Date: Wed, 17 Apr 2019 16:34:47 +0100 Subject: [PATCH] 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. --- 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 f71dedfd8b..02eefe0f58 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -950,10 +950,10 @@ Composite Types @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 db42dfb637..39c5a1ec50 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -87,6 +87,7 @@ Intro Eval (@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 222f863c98..97f7fb9f79 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -38,11 +38,16 @@ What Is a Function @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 fc5ce594e6..25892d4b57 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -1031,10 +1031,9 @@ Writing Emacs Primitives @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 a214a2d3fd..5d71fb39a2 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -558,9 +558,12 @@ Standard Properties 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 @@ Standard Properties 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 -- 2.20.1