[Emacs-diffs] trunk r115853: Remove the dynamic-docstring-function feature.

[Chong Yidong]

------------------------------------------------------------
revno: 115853
revision-id: address@hidden
parent: address@hidden
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Fri 2014-01-03 13:37:58 +0800
message:
  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.
modified:
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/emacs-lisp/advice.el      advice.el-20091113204419-o5vbwnq5f7feedwu-605
  lisp/emacs-lisp/nadvice.el     nadvice.el-20121015213644-851fdxs2vximj8nr-1
  lisp/progmodes/sql.el          sql.el-20091113204419-o5vbwnq5f7feedwu-1303
  src/ChangeLog                  changelog-20091113204419-o5vbwnq5f7feedwu-1438
  src/doc.c                      doc.c-20091113204419-o5vbwnq5f7feedwu-250

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-01-02 09:40:11 +0000
+++ b/etc/NEWS  2014-01-03 05:37:58 +0000
@@ -995,9 +995,6 @@
 ** 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

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-01-03 05:10:52 +0000
+++ b/lisp/ChangeLog    2014-01-03 05:37:58 +0000
@@ -1,3 +1,24 @@
+2014-01-03  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * ielm.el (ielm-tab): Retarget.

=== modified file 'lisp/emacs-lisp/advice.el'
--- a/lisp/emacs-lisp/advice.el 2014-01-01 07:43:34 +0000
+++ b/lisp/emacs-lisp/advice.el 2014-01-03 05:37:58 +0000
@@ -2185,26 +2185,6 @@
                    (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 @@
 
 (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 @@
        ;; 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 @@
     (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.

=== modified file 'lisp/emacs-lisp/nadvice.el'
--- a/lisp/emacs-lisp/nadvice.el        2014-01-01 07:43:34 +0000
+++ b/lisp/emacs-lisp/nadvice.el        2014-01-03 05:37:58 +0000
@@ -67,8 +67,8 @@
 (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 @@
                     (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 @@
         (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 @@
       (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 @@
                           (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)

=== modified file 'lisp/progmodes/sql.el'
--- a/lisp/progmodes/sql.el     2014-01-01 07:43:34 +0000
+++ b/lisp/progmodes/sql.el     2014-01-03 05:37:58 +0000
@@ -2826,14 +2826,14 @@
                      "]\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 @@
 
 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.

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2014-01-02 15:58:48 +0000
+++ b/src/ChangeLog     2014-01-03 05:37:58 +0000
@@ -1,3 +1,7 @@
+2014-01-03  Chong Yidong  <address@hidden>
+
+       * doc.c (Fdocumentation): Remove dynamic-docstring-function.
+
 2014-01-02  Martin Rudalics  <address@hidden>
 
        Further adjust frame/window scrollbar width calculations.

=== modified file 'src/doc.c'
--- a/src/doc.c 2014-01-01 07:43:34 +0000
+++ b/src/doc.c 2014-01-03 05:37:58 +0000
@@ -416,21 +416,6 @@
       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)))