From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Michael Heerdegen Newsgroups: gmane.emacs.bugs Subject: bug#58602: 29.0.50; Please document (:documentation FORM) spec for closures Date: Tue, 18 Oct 2022 05:16:49 +0200 Message-ID: <87h701izxa.fsf@web.de> References: <87r0z69cxj.fsf@web.de> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="6946"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: 58602@debbugs.gnu.org To: Stefan Monnier Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Oct 18 05:18:13 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 1okd7N-0001VS-6q for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 18 Oct 2022 05:18:13 +0200 Original-Received: from localhost ([::1]:54160 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1okd7L-00023z-Fm for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 17 Oct 2022 23:18:11 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59290) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1okd7C-00023q-U4 for bug-gnu-emacs@gnu.org; Mon, 17 Oct 2022 23:18:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:51593) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1okd7C-0006wZ-M3 for bug-gnu-emacs@gnu.org; Mon, 17 Oct 2022 23:18:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1okd7C-0006To-9A for bug-gnu-emacs@gnu.org; Mon, 17 Oct 2022 23:18:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Michael Heerdegen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 18 Oct 2022 03:18:02 +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.166606302524825 (code B ref 58602); Tue, 18 Oct 2022 03:18:02 +0000 Original-Received: (at 58602) by debbugs.gnu.org; 18 Oct 2022 03:17:05 +0000 Original-Received: from localhost ([127.0.0.1]:50671 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1okd6G-0006SL-Qo for submit@debbugs.gnu.org; Mon, 17 Oct 2022 23:17:05 -0400 Original-Received: from mout.web.de ([212.227.17.11]:52745) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1okd6E-0006Rn-PG for 58602@debbugs.gnu.org; Mon, 17 Oct 2022 23:17:03 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=web.de; s=s29768273; t=1666063010; bh=pmrCWNKKwKMApH6u9L/Tk8TjLreVmgK3lKh1wOhVWQg=; h=X-UI-Sender-Class:From:To:Cc:Subject:In-Reply-To:References:Date; b=RbswnA6P25EBWqrs5bpsOKuPhU7av9OUtRbWs2xBLINUgiVHakJV/bfS+1/FcD2ho oCv6/2/MKXSihWXrkZ9U/CS3BnKupwQNQ5qKadbzQihBx6DbM8Zp4xdlg8RfW/xKlo q6QIQjNODj4jrVbhKo58q8HFwmmLuLmzJZ2+XH/ZSYbd/G1+nx9z8ycbrsmy2lyflz tTCEwvZXECDZP0mfiGru6ky60v20r/9KWt4aa4Ck7dwWdGr24XoMKW3Bo5HKLdiJZG k11kGvMlBOI4jm7fzHwCgkIPvYg4Tv2ialoY/H+/dRDESnAbnxegq4UmeZIyPPoi/n vKR+xXfdb/Wmw== X-UI-Sender-Class: 814a7b36-bfc1-4dae-8640-3722d8ec6cd6 Original-Received: from drachen.dragon ([188.105.185.54]) by smtp.web.de (mrweb106 [213.165.67.124]) with ESMTPSA (Nemesis) id 1MlbLM-1pSFIu2QYE-00j0RX; Tue, 18 Oct 2022 05:16:50 +0200 In-Reply-To: (Stefan Monnier's message of "Mon, 17 Oct 2022 22:05:06 -0400") X-Provags-ID: V03:K1:+NAcYnE4JgHe4YK+Wd6rN8NH0Hljw2qPoc3uDVBdgd7MiQB7+XS kbRCtKz1ACnisjgIY90n0jQw7dOWOOIrcCniBixi9Ey3xSqxhz6u6PcqZW/xZY5YSGWsGUz sN3E+TeA/0Z6HXRM6L17ZzcgsKgJiU2WD4effehGo+DX3kMqB+YhoQZws0hsllZGSFXhmkf rXE5meDicnifnRAi0vDsw== X-UI-Out-Filterresults: notjunk:1;V03:K0:viiTzT0Rxlk=:a8tBa3mCBGNXtJjzXy4v2w YTQO+2AIIv+bcH60xg57kJcey2N+yS8KB6Jv3Oy6vpuLWXpiCrs86uWL0Qb+XctIMI4qFExMS PvDDOU3Hks2ckSgwB3a8C89gmOMTJ+LzzWFolK/ZeQ7H00nS9tppODzCt1dk0UNxN27D3a9ZL dfpPYQKJd7w5hthc2ona/CL6l0y2dDoWQkS2Ww5XauIkOOX/zT56oYOkJkicS7Jd4AsMF2GDY khkHqAv84HLQfG6gEBc1GA8dAeaV3TFOE+A29mnXGI+NAAbg2yyfWrKod/MVoDgYUAxqvkmX5 vj4aGkpYxWESk1jW1CeEJ7MfP0O+BM0Lg0jYKlJ4qwu1dL+owZwf32jjfs8Xs5IiC9ZjFVir4 DwAvw0fSp7tdQEhHTKCTMzY7EB+Ekwi1SkW39Pqz20krcoYXv+jHgXPXamgck6f4SKl569k8C ChaW0fGSceHTeL+rc1RIDKjnrOGLPTmpTuPuvNUE3ZPwOCB4Lf6U1RW7uYnZTIO/epv7hOuaI l74VJIV/YGGBKowdfs4Bvx2opisFdm7JHxjcO32KrmoslCBQZnkkviwRSaU2OlOakqbUiwiZv RE7lFIBT+818V2anJ/HPGycj9kgCqOoGa1e/gN+FbYzw2YSlBJPHy27JeYwxl4aVjEXdEC5l0 0ISYIoXaLxELvh6KKjfaS4RJjrdZxkYSTVSQNxhaPtSoiWGtDMcz3b44zMKNnZjaRr5KP+TkU DiqWoB5JBrqyKeU1ITwwzaiv81I2AMNYLRi2pZOIPUUSzpwSCDpCj0UcmQR4gAZ5rOZ0KQMh 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:245774 Archived-At: Stefan Monnier writes: > +Documentation strings are usually completely static, but occasionally > +it can be necessary to generate them dynamically. In some cases this > +can be done by writing a macro which will generate at compile time the > +code of the function, including the desired documentation string. > +But you can also generate the docstring at run-time I wonder: run-time or eval-time? > + when the function > +is defined by writing @code{(:documentation @var{form})} instead of > +the documentation string@footnote{This only works in code using > +@code{lexical-binding}.}. Furthermore, 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 should evaluate to a string. When is that form evaluated? Apart from that, the text is ok for me. Maybe leave out the macro thing (it's not really suitable to define a macro only for the purpose to compute the docstring at compile time, and the other methods are probably as good, so this may be more distracting). And apart from that, I do not know how to write good documentation as well. Thanks, Michael.