From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures Date: Tue, 18 Oct 2022 16:13:25 -0400 Message-ID: References: <87r0z69cxj.fsf@web.de> <87h701izxa.fsf@web.de> Reply-To: Stefan Monnier Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="3352"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) Cc: 58602@debbugs.gnu.org To: Michael Heerdegen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Oct 18 22:14:40 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1oksz1-0000fY-9f for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 18 Oct 2022 22:14:39 +0200 Original-Received: from localhost ([::1]:44098 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oksyz-0004lu-Sq for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 18 Oct 2022 16:14:37 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:40620) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oksyQ-0004kU-Dn for bug-gnu-emacs@gnu.org; Tue, 18 Oct 2022 16:14:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:55107) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oksyQ-00026R-4o for bug-gnu-emacs@gnu.org; Tue, 18 Oct 2022 16:14:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oksyP-0003HH-M9 for bug-gnu-emacs@gnu.org; Tue, 18 Oct 2022 16:14:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Monnier Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 18 Oct 2022 20:14:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 58602 X-GNU-PR-Package: emacs Original-Received: via spool by 58602-submit@debbugs.gnu.org id=B58602.166612402012564 (code B ref 58602); Tue, 18 Oct 2022 20:14:01 +0000 Original-Received: (at 58602) by debbugs.gnu.org; 18 Oct 2022 20:13:40 +0000 Original-Received: from localhost ([127.0.0.1]:54185 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oksy4-0003GZ-12 for submit@debbugs.gnu.org; Tue, 18 Oct 2022 16:13:40 -0400 Original-Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:12314) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oksxz-0003GG-UK for 58602@debbugs.gnu.org; Tue, 18 Oct 2022 16:13:39 -0400 Original-Received: from pmg2.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 2B27C80976; Tue, 18 Oct 2022 16:13:30 -0400 (EDT) Original-Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 2B8B7805DB; Tue, 18 Oct 2022 16:13:28 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1666124008; bh=5JxQSelff6grgHIJ2OKO9z6Kb3hCqmEW1ff8TzkdhCY=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=d+pJNEQEQJ+y7ysE4UuEG/8+7Hrl1d0ieGuC/kutE0Cy7D3LHVfclCly8TuR6aYYu xy1CDBHwSIz8Sv6bVu4GRQ31BTAHnaiQgW8cm0uwJjPmfJuXycwmLlLVYd3XGHHL4O +s2IeN1qKI1s98Ja2H3f3ujr2C5mzeBEou5tx2lq1s40Fcf8FHCY7T5PaFGOseYhG7 AZiDC9eFUn5x7vxnQEZ2steECl1sVbwAXV4ekcW3JVzXZHM4mAXSAMYWsIGLGgKnES 1XN1ZOkchPXiHLxXu+EwmazILENBzey9sO+Rp/untsLvz7gocj+gSNr9rfVvodceoo mxr3X3O9UYDEg== Original-Received: from lechazo (lechon.iro.umontreal.ca [132.204.27.242]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 183EE120DB1; Tue, 18 Oct 2022 16:13:28 -0400 (EDT) In-Reply-To: (Stefan Monnier's message of "Tue, 18 Oct 2022 09:34:29 -0400") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:245830 Archived-At: I pushed the text below. Thanks to Eli and Drew for their review. Stefan PS: BTW, I noticed that `i :documentation RET` doesn't bring me to this text, instead it just looks for "documentation" (which matches many more index entries), disregarding the `:` and making this `@kindex` much less useful. PPS: Every time you use this `function-documentation` property, kitten suffer atrocious pains. diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 8b858e0aa01..94c42ba260d 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -533,6 +533,46 @@ Function Documentation compiler emit a warning message when it compiles Lisp programs which use the deprecated calling convention. +@cindex computed documentation string +@kindex{:documentation} + +Documentation strings are usually static, but occasionally it can be +necessary to generate them dynamically. In some cases you can do so +by writing a macro which generates at compile time the code of the +function, including the desired documentation string. But you can +also generate the docstring dynamically by writing +@code{(:documentation @var{form})} instead of the documentation +string. This will evaluate @var{form} at run-time when the function +is defined and use it as the documentation string@footnote{This only +works in code using @code{lexical-binding}.}. You can also compute +the documentation string on the fly when it is requested, by setting +the @code{function-documentation} property of the function's symbol to +a Lisp form that evaluates to a string. + +For example: +@example +@group +(defun adder (x) + (lambda (y) + (:documentation (format "Add %S to the argument Y." x)) + (+ x y))) +(defalias 'adder5 (adder 5)) +(documentation 'adder5) + @result{} "Add 5 to the argument Y." +@end group + +@group +(put 'adder5 'function-documentation + '(concat (documentation (symbol-function 'adder5) 'raw) + " Consulted at " (format-time-string "%H:%M:%S"))) +(documentation 'adder5) + @result{} "Add 5 to the argument Y. Consulted at 15:52:13" +(documentation 'adder5) + @result{} "Add 5 to the argument Y. Consulted at 15:52:18" +@end group +@end example + + @node Function Names @section Naming a Function @cindex function definition