Add (:documentation <form>) for dynamically-generated docstrings

* lisp/emacs-lisp/bytecomp.el:
(byte-compile-initial-macro-environment): Use macroexp-progn.
(byte-compile-cl-warn): Don't silence use of cl-macroexpand-all.
(byte-compile-file-form-defvar-function): Rename from
byte-compile-file-form-define-abbrev-table.
(defvaralias, byte-compile-file-form-custom-declare-variable): Use it.
(byte-compile): Use byte-compile-top-level rather than
byte-compile-lambda so we can compile non-values.
(byte-compile-form): Add warnings for failed uses of lexical vars via
quoted symbols.
(byte-compile-unfold-bcf): Improve message for failed inlining.
(byte-compile-make-closure): Handle new format of internal-make-closure
for dynamically-generated docstrings.

* lisp/emacs-lisp/cconv.el (cconv--convert-function):
Add `docstring' argument.
(cconv-convert): Use it to handle the new (:documentation ...) form.
(cconv-analyze-form): Handle the new (:documentation ...) form.

* src/eval.c (Ffunction): Handle the new (:documentation ...) form.
(syms_of_eval): Declare `:documentation'.

1 files changed, 4 insertions, 0 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 72e23562868..d72d01f233e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -599,6 +599,10 @@ in languages like German where downcasing rules depend on grammar.
 
 * Lisp Changes in Emacs 25.1
 
+** lexical closures can use (:documentation <form>) to build their docstring.
+It should be placed right where the docstring would be, and <form> is then
+evaluated (and should return a string) when the closure is built.
+
 ** define-inline provides a new way to define inlinable functions.
 
 ** New function macroexpand-1 to perform a single step of macroexpansion.