Give , and .@ doc strings. Fixes bug #24561.

Also make *Help* links to ``' possible.  Also make usable as such doc strings
on the function-documentation property of a symbol.

* lisp/emacs-lisp/backquote.el (top-level): Give , and '@ doc strings on the
function-documentation property.  Also give these symbols a reader-construct
property.

* lisp/help-fns.el (describe-function): Allow the function-documentation
property to work.  Use princ rather than prin1 to print the function's name
when it has a reader-construct property.
(help-fns-signature): Don't insert `high-usage' for a reader-construct.
(describe-function-1): Adapt to process documentation on the
function-documentation property.  Print "a reader construct" when appropriate.

* lisp/help-mode.el (help-xref-symbol-regexp): Amend this regexp also to match
``'.

diff --git a/lisp/emacs-lisp/backquote.el b/lisp/emacs-lisp/backquote.el
index 94c561cba0a5b1ac443645523dbbaa08ad89bcc2..bb877dd2c9705eb6ea6d4de36b647d3ec0939d71 100644 (file)
--- a/lisp/emacs-lisp/backquote.el
+++ b/lisp/emacs-lisp/backquote.el
@@ -247,4 +247,14 @@ LEVEL is only used internally and indicates the nesting level:
        tail))
      (t (cons 'list heads)))))
 
+\f
+;; Give `,' and `,@' documentation strings which can be examined by C-h f.
+(put '\, 'function-documentation
+     "See `\\=`' (also `pcase') for the usage of `,'.")
+(put '\, 'reader-construct t)
+
+(put '\,@ 'function-documentation
+     "See `\\=`' for the usage of `,@'.")
+(put '\,@ 'reader-construct t)
+
 ;;; backquote.el ends here

diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index fa16fa0bb678e00d10ead87e88cb27455246a169..edbcd9099d38db4d84d1d1ce2f37fdbf863091cc 100644 (file)
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -115,13 +115,15 @@ When called from lisp, FUNCTION may also be a function object."
                 (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,9 @@ When called from lisp, FUNCTION may also be a function object."
 
     (save-excursion
       (with-help-window (help-buffer)
-        (prin1 function)
+        (if (get function 'reader-construct)
+            (princ function)
+          (prin1 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 +473,8 @@ suitable file is found, return nil."
         (let ((fill-begin (point))
               (high-usage (car high))
               (high-doc (cdr high)))
-          (insert high-usage "\n")
+          (unless (get function 'reader-construct)
+            (insert high-usage "\n"))
           (fill-region fill-begin (point))
           high-doc)))))
 
@@ -565,18 +570,21 @@ FILE is the file where FUNCTION was probably defined."
          (or (and advised
                    (advice--cd*r (advice--symbol-function function)))
              function))
-        ;; Get the real definition.
+        ;; Get the real definition, if any.
         (def (if (symbolp real-function)
-                 (or (symbol-function real-function)
-                     (signal 'void-function (list real-function)))
+                  (cond ((symbol-function real-function))
+                        ((get real-function 'function-documentation)
+                         nil)
+                        (t (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))))))
+        (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 @@ FILE is the file where FUNCTION was probably defined."
     ;; Print what kind of function-like object FUNCTION is.
     (princ (cond ((or (stringp def) (vectorp def))
                  "a keyboard macro")
+                ((get function 'reader-construct)
+                  "a reader construct")
                 ;; Aliases are Lisp functions, so we need to check
                 ;; aliases before functions.
                 (aliased

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index a8d7294a5cc1d01acdf176924fe97c96eef9c305..3fb793e7aa5e521ab419c5d478eb17b29beb900c 100644 (file)
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -328,7 +328,7 @@ Commands:
                    "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
                    "[ \t\n]+\\)?"
                    ;; Note starting with word-syntax character:
-                   "['`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\)['’]"))
+                   "['`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\|`\\)['’]"))
   "Regexp matching doc string references to symbols.
 
 The words preceding the quoted symbol can be used in doc strings to