From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.bugs Subject: bug#25461: [Patch]: Missing doc strings for "," and ",@". Date: Wed, 18 Jan 2017 19:43:20 +0000 Message-ID: <20170118194320.GB4108@acm.fritz.box> References: <20170116212257.GA4747@acm.fritz.box> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: blaine.gmane.org 1484768677 2300 195.159.176.226 (18 Jan 2017 19:44:37 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 18 Jan 2017 19:44:37 +0000 (UTC) User-Agent: Mutt/1.5.24 (2015-08-30) To: 25461@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Jan 18 20:44:33 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTw9Z-0007DA-4r for geb-bug-gnu-emacs@m.gmane.org; Wed, 18 Jan 2017 20:44:17 +0100 Original-Received: from localhost ([::1]:43911 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cTw9c-000324-If for geb-bug-gnu-emacs@m.gmane.org; Wed, 18 Jan 2017 14:44:20 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:42903) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cTw9O-0002w6-9W for bug-gnu-emacs@gnu.org; Wed, 18 Jan 2017 14:44:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cTw9K-0001hr-Dc for bug-gnu-emacs@gnu.org; Wed, 18 Jan 2017 14:44:06 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:36811) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cTw9K-0001hn-9a for bug-gnu-emacs@gnu.org; Wed, 18 Jan 2017 14:44:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1cTw9K-0004AZ-0w for bug-gnu-emacs@gnu.org; Wed, 18 Jan 2017 14:44:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 18 Jan 2017 19:44:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 25461 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 25461-submit@debbugs.gnu.org id=B25461.148476861715982 (code B ref 25461); Wed, 18 Jan 2017 19:44:01 +0000 Original-Received: (at 25461) by debbugs.gnu.org; 18 Jan 2017 19:43:37 +0000 Original-Received: from localhost ([127.0.0.1]:35010 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTw8u-00049h-RB for submit@debbugs.gnu.org; Wed, 18 Jan 2017 14:43:37 -0500 Original-Received: from ocolin.muc.de ([193.149.48.4]:25642 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cTw8u-00049a-01 for 25461@debbugs.gnu.org; Wed, 18 Jan 2017 14:43:36 -0500 Original-Received: (qmail 90428 invoked by uid 3782); 18 Jan 2017 19:43:34 -0000 Original-Received: from acm.muc.de (p548C6FB5.dip0.t-ipconnect.de [84.140.111.181]) by colin.muc.de (tmda-ofmipd) with ESMTP; Wed, 18 Jan 2017 20:43:34 +0100 Original-Received: (qmail 5400 invoked by uid 1000); 18 Jan 2017 19:43:20 -0000 Content-Disposition: inline In-Reply-To: X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:128215 Archived-At: 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).