From: Chong Yidong Date: Fri, 3 Jan 2014 05:37:58 +0000 (+0800) Subject: Remove the dynamic-docstring-function feature. X-Git-Tag: emacs-24.3.90~173^2^2~42^2~45^2~387^2~86 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=0d53f628be877abf2da4693df620d91d474ec058;p=emacs.git Remove the dynamic-docstring-function feature. * emacs-lisp/advice.el (ad--make-advised-docstring): Change args. Ignore function-documentation property when getting documentation. (ad-activate-advised-definition): Use function-documentation generate the docstring. (ad-make-advised-definition): Don't call ad-make-advised-definition-docstring. (ad-make-advised-definition-docstring, ad-advised-definition-p): Delete functions. * emacs-lisp/nadvice.el (advice--make-docstring): Change args. (advice--docstring): Delete variable. (advice--make-1): Leave the docstring empty. (advice-add): Use function-documentation for advised docstring. * progmodes/sql.el (sql-help): Use function-documentation instead of dynamic-docstring-function property. No need to autoload now. (sql--help-docstring): New variable. (sql--make-help-docstring): Use it. * doc.c (Fdocumentation): Remove dynamic-docstring-function. --- diff --git a/etc/NEWS b/etc/NEWS index 5762ebf0fcd..44764f3cde0 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -995,9 +995,6 @@ selected among several alternatives, as a matter of user preference. ** The `defalias-fset-function' property lets you catch `defalias' calls, and redirect them to your own function, instead of `fset'. -** Docstrings can be made dynamic by adding a `dynamic-docstring-function' -text-property on the first char. - +++ ** New variable `enable-dir-local-variables'. Directory-local variables are ignored if this is nil. This may be diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 1ef042ede2a..6d5cadb7d78 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,24 @@ +2014-01-03 Chong Yidong + + * emacs-lisp/nadvice.el (advice--make-docstring): Change args. + (advice--docstring): Delete variable. + (advice--make-1): Leave the docstring empty. + (advice-add): Use function-documentation for advised docstring. + + * emacs-lisp/advice.el (ad--make-advised-docstring): Change args. + Ignore function-documentation property when getting documentation. + (ad-activate-advised-definition): Use function-documentation + generate the docstring. + (ad-make-advised-definition): Don't call + ad-make-advised-definition-docstring. + (ad-make-advised-definition-docstring, ad-advised-definition-p): + Delete functions. + + * progmodes/sql.el (sql-help): Use function-documentation instead + of dynamic-docstring-function property. No need to autoload now. + (sql--help-docstring): New variable. + (sql--make-help-docstring): Use it. + 2014-01-03 Stefan Monnier * ielm.el (ielm-tab): Retarget. diff --git a/lisp/emacs-lisp/advice.el b/lisp/emacs-lisp/advice.el index a368d0f1ff3..7f0f1506f49 100644 --- a/lisp/emacs-lisp/advice.el +++ b/lisp/emacs-lisp/advice.el @@ -2185,26 +2185,6 @@ Like `interactive-form', but also works on pieces of advice." (if (ad-interactive-form definition) 1 0)) (cdr (cdr (ad-lambda-expression definition))))))) -(defun ad-make-advised-definition-docstring (_function) - "Make an identifying docstring for the advised definition of FUNCTION. -Put function name into the documentation string so we can infer -the name of the advised function from the docstring. This is needed -to generate a proper advised docstring even if we are just given a -definition (see the code for `documentation')." - (eval-when-compile - (propertize "Advice function assembled by advice.el." - 'dynamic-docstring-function - #'ad--make-advised-docstring))) - -(defun ad-advised-definition-p (definition) - "Return non-nil if DEFINITION was generated from advice information." - (if (or (ad-lambda-p definition) - (macrop definition) - (ad-compiled-p definition)) - (let ((docstring (ad-docstring definition))) - (and (stringp docstring) - (get-text-property 0 'dynamic-docstring-function docstring))))) - (defun ad-definition-type (definition) "Return symbol that describes the type of DEFINITION." ;; These symbols are only ever used to check a cache entry's validity. @@ -2498,36 +2478,39 @@ Example: `(ad-map-arglists '(a &rest args) '(w x y z))' will return (require 'help-fns) ;For help-split-fundoc and help-add-fundoc-usage. -(defun ad--make-advised-docstring (origdoc function &optional style) +(defun ad--make-advised-docstring (function &optional style) "Construct a documentation string for the advised FUNCTION. -It concatenates the original documentation with the documentation -strings of the individual pieces of advice which will be formatted -according to STYLE. STYLE can be `plain', everything else -will be interpreted as `default'. The order of the advice documentation -strings corresponds to before/around/after and the individual ordering -in any of these classes." - (if (and (symbolp function) - (string-match "\\`ad-+Advice-" (symbol-name function))) - (setq function - (intern (substring (symbol-name function) (match-end 0))))) - (let* ((usage (help-split-fundoc origdoc function)) - paragraphs advice-docstring) - (setq usage (if (null usage) t (setq origdoc (cdr usage)) (car usage))) - (if origdoc (setq paragraphs (list origdoc))) - (dolist (class ad-advice-classes) - (dolist (advice (ad-get-enabled-advices function class)) - (setq advice-docstring - (ad-make-single-advice-docstring advice class style)) - (if advice-docstring - (push advice-docstring paragraphs)))) - (setq origdoc (if paragraphs - (propertize - ;; separate paragraphs with blank lines: - (mapconcat 'identity (nreverse paragraphs) "\n\n") - ;; FIXME: what is this for? - 'dynamic-docstring-function - #'ad--make-advised-docstring))) - (help-add-fundoc-usage origdoc usage))) +Concatenate the original documentation with the documentation +strings of the individual pieces of advice. Optional argument +STYLE specifies how to format the pieces of advice; it can be +`plain', or any other value which means the default formatting. + +The advice documentation is shown in order of before/around/after +advice type, obeying the priority in each of these types." + ;; Retrieve the original function documentation + (let* ((fun (get function 'function-documentation)) + (origdoc (unwind-protect + (progn (put function 'function-documentation nil) + (documentation function t)) + (put function 'function-documentation fun)))) + (if (and (symbolp function) + (string-match "\\`ad-+Advice-" (symbol-name function))) + (setq function + (intern (substring (symbol-name function) (match-end 0))))) + (let* ((usage (help-split-fundoc origdoc function)) + paragraphs advice-docstring) + (setq usage (if (null usage) t (setq origdoc (cdr usage)) (car usage))) + (if origdoc (setq paragraphs (list origdoc))) + (dolist (class ad-advice-classes) + (dolist (advice (ad-get-enabled-advices function class)) + (setq advice-docstring + (ad-make-single-advice-docstring advice class style)) + (if advice-docstring + (push advice-docstring paragraphs)))) + (setq origdoc (if paragraphs + (mapconcat 'identity (nreverse paragraphs) + "\n\n"))) + (help-add-fundoc-usage origdoc usage)))) ;; @@@ Accessing overriding arglists and interactive forms: @@ -2575,7 +2558,7 @@ in any of these classes." ;; Finally, build the sucker: (ad-assemble-advised-definition advised-arglist - (ad-make-advised-definition-docstring function) + nil interactive-form orig-form (ad-get-enabled-advices function 'before) @@ -2889,6 +2872,8 @@ The current definition and its cache-id will be put into the cache." (fset advicefunname (or verified-cached-definition (ad-make-advised-definition function))) + (put advicefunname 'function-documentation + `(ad--make-advised-docstring ',advicefunname)) (unless (equal (interactive-form advicefunname) old-ispec) ;; If the interactive-spec of advicefunname has changed, force nadvice to ;; refresh its copy. diff --git a/lisp/emacs-lisp/nadvice.el b/lisp/emacs-lisp/nadvice.el index 97b7eec686a..3dfeb04a9b3 100644 --- a/lisp/emacs-lisp/nadvice.el +++ b/lisp/emacs-lisp/nadvice.el @@ -67,8 +67,8 @@ Each element has the form (WHERE BYTECODE STACK) where: (defsubst advice--cdr (f) (aref (aref f 2) 2)) (defsubst advice--props (f) (aref (aref f 2) 3)) -(defun advice--make-docstring (_string function) - "Build the raw doc-string of SYMBOL, presumably advised." +(defun advice--make-docstring (function) + "Build the raw docstring for FUNCTION, presumably advised." (let ((flist (indirect-function function)) (docstring nil)) (if (eq 'macro (car-safe flist)) (setq flist (cdr flist))) @@ -105,13 +105,6 @@ Each element has the form (WHERE BYTECODE STACK) where: (setq origdoc (cdr usage)) (car usage))) (help-add-fundoc-usage (concat docstring origdoc) usage)))) -(defvar advice--docstring - ;; Can't eval-when-compile nor use defconst because it then gets pure-copied, - ;; which drops the text-properties. - ;;(eval-when-compile - (propertize "Advised function" - 'dynamic-docstring-function #'advice--make-docstring)) ;; ) - (defun advice-eval-interactive-spec (spec) "Evaluate the interactive spec SPEC." (cond @@ -144,7 +137,7 @@ Each element has the form (WHERE BYTECODE STACK) where: (advice (apply #'make-byte-code 128 byte-code (vector #'apply function main props) stack-depth - advice--docstring + nil (and (or (commandp function) (commandp main)) (not (and (symbolp main) ;; Don't autoload too eagerly! (autoloadp (symbol-function main)))) @@ -370,7 +363,6 @@ of the piece of advice." (unless (eq oldadv (get symbol 'advice--pending)) (put symbol 'advice--pending (advice--subst-main oldadv nil))) (funcall fsetfun symbol newdef)))) - ;;;###autoload (defun advice-add (symbol where function &optional props) @@ -398,6 +390,7 @@ is defined as a macro, alias, command, ..." (get symbol 'advice--pending)) (t (symbol-function symbol))) function props) + (put symbol 'function-documentation `(advice--make-docstring ',symbol)) (add-function :around (get symbol 'defalias-fset-function) #'advice--defalias-fset)) nil) diff --git a/lisp/progmodes/sql.el b/lisp/progmodes/sql.el index d92d6a66ed2..eb8e0760e25 100644 --- a/lisp/progmodes/sql.el +++ b/lisp/progmodes/sql.el @@ -2826,14 +2826,14 @@ each line with INDENT." "]\n")))) doc)) -;;;###autoload -(eval - ;; FIXME: This dynamic-docstring-function trick doesn't work for byte-compiled - ;; functions, because of the lazy-loading of docstrings, which strips away - ;; text properties. - '(defun sql-help () - #("Show short help for the SQL modes. +(defun sql-help () + "Show short help for the SQL modes." + (interactive) + (describe-function 'sql-help)) +(put 'sql-help 'function-documentation '(sql--make-help-docstring)) +(defvar sql--help-docstring + "Show short help for the SQL modes. Use an entry function to open an interactive SQL buffer. This buffer is usually named `*SQL*'. The name of the major mode is SQLi. @@ -2862,24 +2862,20 @@ anything. The name of the major mode is SQL. In this SQL buffer (SQL mode), you can send the region or the entire buffer to the interactive SQL buffer (SQLi mode). The results are -appended to the SQLi buffer without disturbing your SQL buffer." - 0 1 (dynamic-docstring-function sql--make-help-docstring)) - (interactive) - (describe-function 'sql-help))) - -(defun sql--make-help-docstring (doc _fun) - "Insert references to loaded products into the help buffer string." - - ;; Insert FREE software list - (when (string-match "^\\(\\s-*\\)[\\\\][\\\\]FREE\\s-*\n" doc 0) - (setq doc (replace-match (sql-help-list-products (match-string 1 doc) t) - t t doc 0))) - - ;; Insert non-FREE software list - (when (string-match "^\\(\\s-*\\)[\\\\][\\\\]NONFREE\\s-*\n" doc 0) - (setq doc (replace-match (sql-help-list-products (match-string 1 doc) nil) - t t doc 0))) - doc) +appended to the SQLi buffer without disturbing your SQL buffer.") + +(defun sql--make-help-docstring () + "Return a docstring for `sql-help' listing loaded SQL products." + (let ((doc sql--help-docstring)) + ;; Insert FREE software list + (when (string-match "^\\(\\s-*\\)[\\\\][\\\\]FREE\\s-*$" doc 0) + (setq doc (replace-match (sql-help-list-products (match-string 1 doc) t) + t t doc 0))) + ;; Insert non-FREE software list + (when (string-match "^\\(\\s-*\\)[\\\\][\\\\]NONFREE\\s-*$" doc 0) + (setq doc (replace-match (sql-help-list-products (match-string 1 doc) nil) + t t doc 0))) + doc)) (defun sql-default-value (var) "Fetch the value of a variable. diff --git a/src/ChangeLog b/src/ChangeLog index 325e428bfeb..1f68372f31a 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,7 @@ +2014-01-03 Chong Yidong + + * doc.c (Fdocumentation): Remove dynamic-docstring-function. + 2014-01-02 Martin Rudalics Further adjust frame/window scrollbar width calculations. diff --git a/src/doc.c b/src/doc.c index 0d9c8021cdf..ecefd776b85 100644 --- a/src/doc.c +++ b/src/doc.c @@ -416,21 +416,6 @@ string is passed through `substitute-command-keys'. */) xsignal1 (Qinvalid_function, fun); } - /* Check for a dynamic docstring. These come with - a dynamic-docstring-function text property. */ - if (STRINGP (doc)) - { - Lisp_Object func - = Fget_text_property (make_number (0), - intern ("dynamic-docstring-function"), - doc); - if (!NILP (func)) - /* Pass both `doc' and `function' since `function' can be needed, and - finding `doc' can be annoying: calling `documentation' is not an - option because it would infloop. */ - doc = call2 (func, doc, function); - } - /* If DOC is 0, it's typically because of a dumped file missing from the DOC file (bug in src/Makefile.in). */ if (EQ (doc, make_number (0)))