[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] master 4430a9b: Improve pure and side-effect-free docs
From: |
Basil L. Contovounesios |
Subject: |
[Emacs-diffs] master 4430a9b: Improve pure and side-effect-free docs |
Date: |
Mon, 22 Apr 2019 08:57:01 -0400 (EDT) |
branch: master
commit 4430a9b54fca266e48d0eb8b72d83706910f10b8
Author: Basil L. Contovounesios <address@hidden>
Commit: Basil L. Contovounesios <address@hidden>
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 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 db42dfb..39c5a1ec 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
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 222f863..97f7fb9 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 fc5ce59..25892d4 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
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] master 4430a9b: Improve pure and side-effect-free docs,
Basil L. Contovounesios <=