[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#25461: [Patch #2]: Missing doc strings for "," and ",@".
From: |
Alan Mackenzie |
Subject: |
bug#25461: [Patch #2]: Missing doc strings for "," and ",@". |
Date: |
Sat, 21 Jan 2017 20:46:48 +0000 |
User-agent: |
Mutt/1.7.2 (2016-11-26) |
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)))))
+
+;; 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).
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., (continued)
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/19
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Noam Postavsky, 2017/01/19
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/19
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Michael Heerdegen, 2017/01/19
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Michael Heerdegen, 2017/01/18
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/19
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Michael Heerdegen, 2017/01/19
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/20
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Michael Heerdegen, 2017/01/20
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/21
- bug#25461: [Patch #2]: Missing doc strings for "," and ",@".,
Alan Mackenzie <=
- bug#25461: [Patch #2]: Missing doc strings for "," and ",@"., Michael Heerdegen, 2017/01/23
- bug#25461: [Patch #2]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/24
- bug#25461: [Patch #2]: Missing doc strings for "," and ",@"., npostavs, 2017/01/23
- bug#25461: [Patch #2]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/24
- bug#25461: [Patch #2]: Missing doc strings for "," and ",@"., Noam Postavsky, 2017/01/24
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/23