bug#25461: [Patch]: Missing doc strings for "," and ",@".

[Alan Mackenzie]

Hello, Emacs.

On Mon, Jan 16, 2017 at 09:24:02PM +0000, GNU bug Tracking System wrote:
> Thank you for filing a new bug report with debbugs.gnu.org.

[ .... ]

Thanks for the comments, so far.  Here is a patch which gives , and ,@
doc strings.  It also creates a mechanism by which other reader macros
(such as ' and #') can be given doc strings later.

I'll just point out one thing I'm proposing changing.  That is, to use
princ rather than prin1 to print the name of the function.  This causes,
for example, backtick to be printed as

    `

rather than the

    \`

we get at the moment.  This might cause problems for function names
which include backslashes or unprintable characters such as \n.

Are there objections to me installing the patch in master?



diff --git a/lisp/emacs-lisp/backquote.el b/lisp/emacs-lisp/backquote.el
index 94c561c..86ca010 100644
--- a/lisp/emacs-lisp/backquote.el
+++ b/lisp/emacs-lisp/backquote.el
@@ -247,4 +247,33 @@ backquote-listify
        tail))
      (t (cons 'list heads)))))
 
+
+;; Give `,' and `,@' documentation strings which can be examined by C-h f.
+(put '\, 'function-documentation
+     "`,' signals that the next form should be evaluated and inserted.
+It can occur only in `\\=`' constructs.
+
+For example:
+
+b              => (ba bb bc)           ; assume b has this value
+\\=`(a ,b c)      => (a (ba bb bc) c)  ; insert the value of b
+
+See also `\\=`' and `,@'.
+
+Note that `,' is also used by the macro `pcase' and the like,
+with radically different semantics.")
+(put '\, 'reader-macro t)
+
+(put '\,@ 'function-documentation
+     ",@ signals that the next form should be evaluated and spliced in.
+It can occur only in `\\=`' constructs.
+
+For example:
+
+b              => (ba bb bc)           ; assume b has this value
+\\=`(a ,@b c)     => (a ba bb bc c)    ; splice in the value of b
+
+See also `\\=`' and `,'.")
+(put '\,@ 'reader-macro t)
+
 ;;; backquote.el ends here
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index fa16fa0..069dc3c 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -115,13 +115,15 @@ describe-function
                 (if fn
                     (format "Describe function (default %s): " fn)
                   "Describe function: ")
-                #'help--symbol-completion-table #'fboundp t nil nil
+                #'help--symbol-completion-table
+                (lambda (f) (or (fboundp f) (get f 'function-documentation)))
+                t nil nil
                 (and fn (symbol-name fn)))))
      (unless (equal val "")
        (setq fn (intern val)))
      (unless (and fn (symbolp fn))
        (user-error "You didn't specify a function symbol"))
-     (unless (fboundp fn)
+     (unless (or (fboundp fn) (get fn 'function-documentation))
        (user-error "Symbol's function definition is void: %s" fn))
      (list fn)))
 
@@ -144,7 +146,7 @@ describe-function
 
     (save-excursion
       (with-help-window (help-buffer)
-        (prin1 function)
+        (princ function)
         ;; Use " is " instead of a colon so that
         ;; it is easier to get out the function name using forward-sexp.
         (princ " is ")
@@ -469,7 +471,8 @@ help-fns--signature
         (let ((fill-begin (point))
               (high-usage (car high))
               (high-doc (cdr high)))
-          (insert high-usage "\n")
+          (unless (get function 'reader-macro)
+            (insert high-usage "\n"))
           (fill-region fill-begin (point))
           high-doc)))))
 
@@ -565,18 +568,23 @@ describe-function-1
          (or (and advised
                    (advice--cd*r (advice--symbol-function function)))
              function))
-        ;; Get the real definition.
-        (def (if (symbolp real-function)
-                 (or (symbol-function real-function)
-                     (signal 'void-function (list real-function)))
-               real-function))
-        (aliased (or (symbolp def)
-                     ;; Advised & aliased function.
-                     (and advised (symbolp real-function)
-                          (not (eq 'autoload (car-safe def))))
-                      (and (subrp def)
-                           (not (string= (subr-name def)
-                                         (symbol-name function))))))
+        ;; Get the real definition, if any.
+        (def (cond ((and (symbolp real-function)
+                          (symbol-function real-function)))
+                    ((and (symbolp real-function)
+                          (get real-function 'function-documentation))
+                     nil)
+                    ((symbolp real-function)
+                     (signal 'void-function (list real-function)))
+                    (t real-function)))
+        (aliased (and def
+                       (or (symbolp def)
+                           ;; Advised & aliased function.
+                           (and advised (symbolp real-function)
+                                (not (eq 'autoload (car-safe def))))
+                           (and (subrp def)
+                                (not (string= (subr-name def)
+                                              (symbol-name function)))))))
         (real-def (cond
                     ((and aliased (not (subrp def)))
                      (let ((f real-function))
@@ -605,6 +613,8 @@ describe-function-1
     ;; Print what kind of function-like object FUNCTION is.
     (princ (cond ((or (stringp def) (vectorp def))
                  "a keyboard macro")
+                ((get function 'reader-macro)
+                  "a reader macro")
                 ;; Aliases are Lisp functions, so we need to check
                 ;; aliases before functions.
                 (aliased


-- 
Alan Mackenzie (Nuremberg, Germany).