all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Alan Mackenzie <acm@muc.de>
To: Michael Heerdegen <michael_heerdegen@web.de>
Cc: 25461@debbugs.gnu.org
Subject: bug#25461: [Patch #2]: Missing doc strings for "," and ",@".
Date: Sat, 21 Jan 2017 20:46:48 +0000	[thread overview]
Message-ID: <20170121204648.GA21091@acm> (raw)
In-Reply-To: <20170121155651.GB5394@acm>

Hello again, Michael.

On Sat, Jan 21, 2017 at 15:56:51 +0000, Alan Mackenzie wrote:
> Hello, Michael.

> On Sat, Jan 21, 2017 at 03:26:06 +0100, Michael Heerdegen wrote:

[ .... ]

> How about starting on a different tack.  Would you accept , and ,@
> having doc strings, with the entirety of these being:

> [for ,]:
>     See ``' (and also `pcase') for the details of `,'.

> [for ,@]:
>     See ``' for the details of `,@'.

> ?


I've hacked all this together.  What used to be called a "reader macro"
is now a "reader construct".  I've made the ``' a clickable link, too.

Is there anything else you think needs changing?



diff --git a/lisp/emacs-lisp/backquote.el b/lisp/emacs-lisp/backquote.el
index 94c561c..acc3fa4 100644
--- a/lisp/emacs-lisp/backquote.el
+++ b/lisp/emacs-lisp/backquote.el
@@ -247,4 +247,14 @@ backquote-listify
 	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 details of `,'.")
+(put '\, 'reader-construct t)
+
+(put '\,@ 'function-documentation
+     "See `\\=`' or `,' for the details of `,@'.")
+(put '\,@ 'reader-construct t)
+
 ;;; backquote.el ends here
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index fa16fa0..edbcd90 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,9 @@ describe-function
 
     (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 @@ help-fns--signature
         (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 @@ describe-function-1
 	  (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 @@ 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-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 a8d7294..3fb793e 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -328,7 +328,7 @@ help-xref-symbol-regexp
 		    "\\(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


-- 
Alan Mackenzie (Nuremberg, Germany).





  reply	other threads:[~2017-01-21 20:46 UTC|newest]

Thread overview: 27+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-01-16 21:22 bug#25461: Missing doc strings for "," and ",@" Alan Mackenzie
2017-01-17 19:34 ` Glenn Morris
2017-01-17 19:56   ` Alan Mackenzie
2017-01-17 20:36     ` Andreas Schwab
2017-01-17 20:41       ` Alan Mackenzie
2017-01-17 20:53         ` Andreas Schwab
2017-01-18  1:44         ` Michael Heerdegen
2017-01-18 19:28           ` Alan Mackenzie
     [not found] ` <handler.25461.B.148460180922707.ack@debbugs.gnu.org>
2017-01-18 19:43   ` bug#25461: [Patch]: " Alan Mackenzie
2017-01-19  0:16     ` npostavs
2017-01-19 17:37       ` Alan Mackenzie
2017-01-19 18:10         ` Noam Postavsky
2017-01-19 18:36           ` Alan Mackenzie
2017-01-20  0:24             ` Michael Heerdegen
2017-01-19  2:23     ` Michael Heerdegen
2017-01-19 17:58       ` Alan Mackenzie
2017-01-20  0:12         ` Michael Heerdegen
2017-01-20 16:58           ` Alan Mackenzie
2017-01-21  2:26             ` Michael Heerdegen
2017-01-21 15:56               ` Alan Mackenzie
2017-01-21 20:46                 ` Alan Mackenzie [this message]
2017-01-24  1:58                   ` bug#25461: [Patch #2]: " Michael Heerdegen
2017-01-24 19:43                     ` Alan Mackenzie
2017-01-24  4:01                   ` npostavs
2017-01-24 19:39                     ` Alan Mackenzie
2017-01-24 20:00                       ` Noam Postavsky
2017-01-23 19:09               ` bug#25461: [Patch]: " Alan Mackenzie

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20170121204648.GA21091@acm \
    --to=acm@muc.de \
    --cc=25461@debbugs.gnu.org \
    --cc=michael_heerdegen@web.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.