* doc/lispref/functions.texi (Declare Form): Document gv-expander,

gv-setter, and compiler-macro.

Fixes: debbugs:16829

2 files changed, 55 insertions, 12 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 706fe131d7b..fe00e5a7b53 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2014-02-22  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * functions.texi (Declare Form): Document gv-expander, gv-setter, and
+        compiler-macro (bug#16829).
+
 2014-02-21  Juanma Barranquero  <lekktu@gmail.com>
 
         * windows.texi (Window Configurations): Doc fix.
@@ -16,6 +21,11 @@
 
         * functions.texi (Defining Functions): Mention defalias-fset-function.
 
+2014-02-17  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * minibuf.texi (Completion Commands): Don't document obsolete
+        `common-substring' arg of display-completion-list.
+
 2014-02-17  Glenn Morris  <rgm@gnu.org>
 
         * minibuf.texi (Text from Minibuffer): Update read-regexp details.
@@ -31,8 +41,8 @@
 
 2014-02-10  Lars Ingebrigtsen  <larsi@gnus.org>
 
-        * text.texi (User-Level Deletion): Document
-        `delete-trailing-whitespace' (bug#15309).
+        * text.texi (User-Level Deletion):
+        Document `delete-trailing-whitespace' (bug#15309).
 
 2014-02-09  Lars Ingebrigtsen  <larsi@gnus.org>
 
@@ -237,8 +247,8 @@
 2013-12-24  Tassilo Horn  <tsdh@gnu.org>
 
         * control.texi (Pattern matching case statement): Fix missing
-        argument in simple expression language sample (Bug#16238).  Add
-        some sample programs written in that language.  Mention that
+        argument in simple expression language sample (Bug#16238).
+        Add some sample programs written in that language.  Mention that
         `pcase' requires lexical binding.
 
 2013-12-23  Xue Fuqiao  <xfq.free@gmail.com>
@@ -253,8 +263,8 @@
 
 2013-12-23  Chong Yidong  <cyd@gnu.org>
 
-        * keymaps.texi (Controlling Active Maps): Renamed
-        set-temporary-overlay-map to set-transient map.  Doc fixes.
+        * keymaps.texi (Controlling Active Maps):
+        Rename set-temporary-overlay-map to set-transient map.  Doc fixes.
         (Searching Keymaps): The transient keymap takes precedence.
 
 2013-12-23  Glenn Morris  <rgm@gnu.org>
@@ -523,8 +533,8 @@
 2013-10-08  Eli Zaretskii  <eliz@gnu.org>
 
         Support menus on text-mode terminals.
-        * keymaps.texi (Defining Menus, Mouse Menus, Menu Bar): Modify
-        wording to the effect that menus are supported on TTYs.
+        * keymaps.texi (Defining Menus, Mouse Menus, Menu Bar):
+        Modify wording to the effect that menus are supported on TTYs.
 
         * frames.texi (Pop-Up Menus, Dialog Boxes)
         (Display Feature Testing): Update for menu support on TTYs.
@@ -731,8 +741,8 @@
 2013-07-22  Michael Albinus  <michael.albinus@gmx.de>
 
         * files.texi (Magic File Names): Add file-notify-add-watch,
-        file-notify-rm-watch and file-notify-supported-p.  Move
-        file-remote-p down.
+        file-notify-rm-watch and file-notify-supported-p.
+        Move file-remote-p down.
 
         * errors.texi (Standard Errors): Add file-notify-error.
 
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 0781eaf056c..b2bd22e9ffd 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1554,14 +1554,17 @@ following effects:
 This acts like a call to @code{set-advertised-calling-convention}
 (@pxref{Obsolete Functions}); @var{signature} specifies the correct
 argument list for calling the function or macro, and @var{when} should
-be a string indicating when the variable was first made obsolete.
+be a string indicating when the old argument list was first made obsolete.
 
 @item (debug @var{edebug-form-spec})
 This is valid for macros only.  When stepping through the macro with
 Edebug, use @var{edebug-form-spec}.  @xref{Instrumenting Macro Calls}.
 
 @item (doc-string @var{n})
-Use element number @var{n}, if any, as the documentation string.
+This is used when defining a function or macro which itself will be used to
+define entities like functions, macros, or variables.  It indicates that
+the @var{n}th argument, if any, should be considered
+as a documentation string.
 
 @item (indent @var{indent-spec})
 Indent calls to this function or macro according to @var{indent-spec}.
@@ -1576,7 +1579,37 @@ instead), a string (specifying the warning message), or @code{nil} (in
 which case the warning message gives no extra details).  @var{when}
 should be a string indicating when the function or macro was first
 made obsolete.
+
+@item (compiler-macro @var{expander})
+This can only be used for functions, and tells the compiler to use
+@var{expander} as an optimization function.  When encountering a call to the
+function, of the form @code{(@var{function} @var{args}@dots)}, the macro
+expander will call @var{expander} with that form as well as with
+@var{args}@dots, and @var{expander} can either return a new expression to use
+instead of the function call, or it can return just the form unchanged,
+to indicate that the function call should be left alone.  @var{expander} can
+be a symbol, or it can be a form @code{(lambda (@var{arg}) @var{body})} in
+which case @var{arg} will hold the original function call expression, and the
+(unevaluated) arguments to the function can be accessed using the function's
+formal arguments.
+
+@item (gv-expander @var{expander})
+Declare @var{expander} to be the function to handle calls to the macro (or
+function) as a generalized variable, similarly to @code{gv-define-expander}.
+@var{expander} can be a symbol or it can be of the form @code{(lambda
+(@var{arg}) @var{body})} in which case that function will additionally have
+access to the macro (or function)'s arguments.
+
+@item (gv-setter @var{setter})
+Declare @var{setter} to be the function to handle calls to the macro (or
+function) as a generalized variable.  @var{setter} can be a symbol in which
+case it will be passed to @code{gv-define-simple-setter}, or it can be of the
+form @code{(lambda (@var{arg}) @var{body})} in which case that function will
+additionally have access to the macro (or function)'s arguments and it will
+passed to @code{gv-define-setter}.
+
 @end table
+
 @end defmac
 
 @node Declaring Functions