From unknown Mon Jun 16 23:31:54 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#54732 <54732@debbugs.gnu.org> To: bug#54732 <54732@debbugs.gnu.org> Subject: Status: 29.0.50; New `function-documentation` Reply-To: bug#54732 <54732@debbugs.gnu.org> Date: Tue, 17 Jun 2025 06:31:54 +0000 retitle 54732 29.0.50; New `function-documentation` reassign 54732 emacs submitter 54732 Stefan Monnier severity 54732 normal thanks From debbugs-submit-bounces@debbugs.gnu.org Tue Apr 05 13:28:55 2022 Received: (at submit) by debbugs.gnu.org; 5 Apr 2022 17:28:55 +0000 Received: from localhost ([127.0.0.1]:56047 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nbmz8-0001kN-FA for submit@debbugs.gnu.org; Tue, 05 Apr 2022 13:28:54 -0400 Received: from lists.gnu.org ([209.51.188.17]:50000) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nbmz7-0001kE-9N for submit@debbugs.gnu.org; Tue, 05 Apr 2022 13:28:54 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51976) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nbmz7-0007qP-4u for bug-gnu-emacs@gnu.org; Tue, 05 Apr 2022 13:28:53 -0400 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:19237) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nbmz4-0002G3-2b for bug-gnu-emacs@gnu.org; Tue, 05 Apr 2022 13:28:51 -0400 Received: from pmg1.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id F1F6D1001E0 for ; Tue, 5 Apr 2022 13:28:47 -0400 (EDT) Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id 8182B10009E for ; Tue, 5 Apr 2022 13:28:38 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1649179718; bh=OjB2j3LfDhnCw0JFuZwzeF25CXFpqKXjWPm/L8iFWTU=; h=From:To:Subject:Date:From; b=gWXYSABHJCEYqm9NZCgMscpA3EFoO+56P5qOhrZOxVOKqLFISMZBFtIe7NLuiiRpQ DO+XDZ/ubGo1sd1r1zYGQXxlIaxM2apIiT9QeMj2gj65OQOs5j3862EKu4sTd9Osjl n+mmpMweznQ87CfYbOYavjHy1ovuvLHs3scfYFuPiWR/Ln4HRLQUznLUIS6l2akiRF wI0/3Lfu24zwqzPT25eWNX3bD32qzypYBhgwYYSL9XlA8d2Zb4mw5xt4vHiSwZnolx balpxGw2vmDj6awRlkF/aMoYnrYqxSLSmZ5DCe27zwq1/c7QoGPS5e32HDTr1gj7Yp GvHUdk9VT21pQ== Received: from pastel (unknown [45.72.221.51]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 5E0AA1202DB for ; Tue, 5 Apr 2022 13:28:38 -0400 (EDT) From: Stefan Monnier To: bug-gnu-emacs@gnu.org Subject: 29.0.50; New `function-documentation` Date: Tue, 05 Apr 2022 13:28:31 -0400 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-SPAM-INFO: Spam detection results: 0 ALL_TRUSTED -1 Passed through trusted hosts only via SMTP AWL -0.047 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DKIM_SIGNED 0.1 Message has a DKIM or DK signature, not necessarily valid DKIM_VALID -0.1 Message has at least one valid DKIM or DK signature DKIM_VALID_AU -0.1 Message has a valid DKIM or DK signature from author's domain T_SCC_BODY_TEXT_LINE -0.01 - X-SPAM-LEVEL: Received-SPF: pass client-ip=132.204.25.50; envelope-from=monnier@iro.umontreal.ca; helo=mailscanner.iro.umontreal.ca X-Spam_score_int: -42 X-Spam_score: -4.3 X-Spam_bar: ---- X-Spam_report: (-4.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: -1.3 (-) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) Package: Emacs Version: 29.0.50 As mentioned in the original OClosure commit, OClosures (ab)use the bytecode's docstring slot to hold the OClosure's type. This currently prevents OClosures from having their own docstring. The patch below lifts this restriction by introducing a new generic function `function-documentation` to fetch the docstring of a function, which can then be implemented in various different ways depending on the OClosure's type. The patch includes one such use, tho there will be others. [ I thought I had sent this patch a few days ago but can't find it on debbugs, so something must have gone wrong on my end when i sent it. In that earlier version the function was called `function-docstring`. ] Comments? Objections? Stefan 2022-04-05 Stefan Monnier * lisp/simple.el (function-documentation): New generic function. (bad-package-check): Strength-reduce `eval` to `symbol-value`. * src/doc.c (Fdocumentation): Use it. * lisp/emacs-lisp/oclosure.el (oclosure--accessor-docstring): New funct= ion. * test/lisp/emacs-lisp/oclosure-tests.el (oclosure-test): Add test for accessor's docstrings. diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 10a12940a15..d53bfad8e9e 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -158,6 +158,13 @@ Accessing Documentation @code{documentation} returns @code{nil}. @end defun =20 +@defun function-documentation function +Generic function used by @code{documentation} to extract the raw +docstring from a function object. You can specify how to get the +docstring of a specific function type by adding a corresponding method +to it. +@end defun + @defun face-documentation face This function returns the documentation string of @var{face} as a face. diff --git a/etc/NEWS b/etc/NEWS index 640e18c6bdc..d138f5f68f7 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1314,6 +1314,12 @@ This change is now applied in 'dired-insert-director= y'. 'unify-8859-on-decoding-mode', 'unify-8859-on-encoding-mode', 'vc-arch-command'. =20 ++++ +** New generic function 'function-doumentation'. +Can dynamically generate a raw docstring depending on the type of +a function. +Used mainly for docstrings of OClosures. + +++ ** Base64 encoding no longer tolerates latin-1 input. The functions 'base64-encode-string', 'base64url-encode-string', diff --git a/lisp/emacs-lisp/oclosure.el b/lisp/emacs-lisp/oclosure.el index 3df64ad2806..90811199f25 100644 --- a/lisp/emacs-lisp/oclosure.el +++ b/lisp/emacs-lisp/oclosure.el @@ -505,6 +505,12 @@ accessor "OClosure function to access a specific slot of an object." type slot) =20 +(defun oclosure--accessor-docstring (f) + ;; This would like to be a (cl-defmethod function-documentation ...) + ;; but for circularity reason the defmethod is in `simple.el'. + (format "Access slot \"%S\" of OBJ of type `%S'.\n\n(fn OBJ)" + (accessor--slot f) (accessor--type f))) + (oclosure-define (oclosure-accessor (:parent accessor) (:copier oclosure--accessor-copy (type slot index))) diff --git a/lisp/simple.el b/lisp/simple.el index 7918767a756..9416a13b7ab 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -2357,6 +2357,37 @@ execute-extended-command-for-buffer (with-suppressed-warnings ((interactive-only execute-extended-command)) (execute-extended-command prefixarg command-name typed))) =20 +(cl-defgeneric function-documentation (function) + "Extract the raw docstring info from FUNCTION. +FUNCTION is expected to be a function value rather than, say, a mere symbo= l. +It is usually preferable to call `documentation' which will call this +function as needed." + (let ((docstring-p (lambda (doc) + ;; A docstring can be either a string or a reference + ;; into either the `etc/DOC' or a `.elc' file. + (or (stringp doc) + (fixnump doc) (fixnump (cdr-safe doc)))))) + (pcase function + ((pred byte-code-function-p) + (when (> (length function) 4) + (let ((doc (aref function 4))) + (when (funcall docstring-p doc) doc)))) + ((or (pred stringp) (pred vectorp)) "Keyboard macro.") + (`(keymap . ,_) + "Prefix command (definition is a keymap associating keystrokes with= commands).") + ((or `(lambda ,_args . ,body) `(closure ,_env ,_args . ,body) + `(autoload ,_file . ,body)) + (let ((doc (car body))) + (when (and (funcall docstring-p doc) + ;; Handle a doc reference--but these never come last + ;; in the function body, so reject them if they are last. + (or (cdr body) (eq 'autoload (car-safe function)))) + doc))) + (_ (signal 'invalid-function (list function)))))) + +(cl-defmethod function-documentation ((function accessor)) + (oclosure--accessor-docstring function)) ;; FIXME: =CE=B7-reduce! + (defun command-execute (cmd &optional record-flag keys special) ;; BEWARE: Called directly from the C code. "Execute CMD as an editor command. @@ -9980,7 +10011,7 @@ bad-package-check (and list (boundp symbol) (or (eq symbol t) - (and (stringp (setq symbol (eval symbol))) + (and (stringp (setq symbol (symbol-value symbol))) (string-match-p (nth 2 list) symbol))) (display-warning package (nth 3 list) :warning))) (error nil))) diff --git a/src/doc.c b/src/doc.c index e361a86c1a1..5326195c6a0 100644 --- a/src/doc.c +++ b/src/doc.c @@ -341,56 +341,8 @@ DEFUN ("documentation", Fdocumentation, Sdocumentation= , 1, 2, 0, else if (MODULE_FUNCTIONP (fun)) doc =3D module_function_documentation (XMODULE_FUNCTION (fun)); #endif - else if (COMPILEDP (fun)) - { - if (PVSIZE (fun) <=3D COMPILED_DOC_STRING) - return Qnil; - else - { - Lisp_Object tem =3D AREF (fun, COMPILED_DOC_STRING); - if (STRINGP (tem)) - doc =3D tem; - else if (FIXNATP (tem) || CONSP (tem)) - doc =3D tem; - else - return Qnil; - } - } - else if (STRINGP (fun) || VECTORP (fun)) - { - return build_string ("Keyboard macro."); - } - else if (CONSP (fun)) - { - Lisp_Object funcar =3D XCAR (fun); - if (!SYMBOLP (funcar)) - xsignal1 (Qinvalid_function, fun); - else if (EQ (funcar, Qkeymap)) - return build_string ("Prefix command (definition is a keymap associating = keystrokes with commands)."); - else if (EQ (funcar, Qlambda) - || (EQ (funcar, Qclosure) && (fun =3D XCDR (fun), 1)) - || EQ (funcar, Qautoload)) - { - Lisp_Object tem1 =3D Fcdr (Fcdr (fun)); - Lisp_Object tem =3D Fcar (tem1); - if (STRINGP (tem)) - doc =3D tem; - /* Handle a doc reference--but these never come last - in the function body, so reject them if they are last. */ - else if ((FIXNATP (tem) || (CONSP (tem) && FIXNUMP (XCDR (tem)))) - && !NILP (XCDR (tem1))) - doc =3D tem; - else - return Qnil; - } - else - goto oops; - } else - { - oops: - xsignal1 (Qinvalid_function, fun); - } + doc =3D call1 (intern ("function-documentation"), fun); =20 /* If DOC is 0, it's typically because of a dumped file missing from the DOC file (bug in src/Makefile.in). */ diff --git a/test/lisp/emacs-lisp/oclosure-tests.el b/test/lisp/emacs-lisp/= oclosure-tests.el index d3e2b3870a6..b6bdebc0a2b 100644 --- a/test/lisp/emacs-lisp/oclosure-tests.el +++ b/test/lisp/emacs-lisp/oclosure-tests.el @@ -65,6 +65,7 @@ oclosure-test (should (member (oclosure-test-gen ocl1) '("#>>" "#>>"))) + (should (stringp (documentation #'oclosure-test--fst))) )) =20 (ert-deftest oclosure-test-limits () From debbugs-submit-bounces@debbugs.gnu.org Wed Apr 06 05:29:59 2022 Received: (at 54732) by debbugs.gnu.org; 6 Apr 2022 09:29:59 +0000 Received: from localhost ([127.0.0.1]:56940 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nc1zD-0000zO-BC for submit@debbugs.gnu.org; Wed, 06 Apr 2022 05:29:59 -0400 Received: from quimby.gnus.org ([95.216.78.240]:35090) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nc1zC-0000z8-1E for 54732@debbugs.gnu.org; Wed, 06 Apr 2022 05:29:58 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=sYuTAT8uHIF0+AGxvfcYGOqEJytAeeOnIdvpakluPg4=; b=I4uFlK2Rj0Z+8E90cLQps3mwU4 sE7FsIsyF4jpJTWSDH4H/YxDFN03tlrunZ72MzyyfZCdyEG5tDY1zfcjIiuJhx7SXHTmUHi4jNtlH 5Mv9GXcCy8MncMjavy71+CoXYAwHe3ulRWL/sPbVPh5FH7DuWALm5xyYXcXrmq4LJ5gc=; Received: from [84.212.220.105] (helo=xo) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nc1z1-00019b-SW; Wed, 06 Apr 2022 11:29:50 +0200 From: Lars Ingebrigtsen To: Stefan Monnier Subject: Re: bug#54732: 29.0.50; New `function-documentation` References: Date: Wed, 06 Apr 2022 11:29:46 +0200 In-Reply-To: (Stefan Monnier's message of "Tue, 05 Apr 2022 13:28:31 -0400") Message-ID: <87fsmqef05.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Stefan Monnier writes: > The patch below lifts this restriction by introducing a new generic > function `function-documentation` to fetch the docstring of a function, > which can then be implemented in various different way [...] Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 54732 Cc: 54732@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Stefan Monnier writes: > The patch below lifts this restriction by introducing a new generic > function `function-documentation` to fetch the docstring of a function, > which can then be implemented in various different ways depending on the > OClosure's type. Makes sense to me. Perhaps the doc string should also say that the reason that `function-documentation' exists is to allow specialisation, and that it should (probably) never be called from code directly, instead of just saying that `documentation' is preferable: + "Extract the raw docstring info from FUNCTION. +FUNCTION is expected to be a function value rather than, say, a mere symbol. +It is usually preferable to call `documentation' which will call this +function as needed." -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Thu Apr 07 16:00:14 2022 Received: (at 54732-done) by debbugs.gnu.org; 7 Apr 2022 20:00:14 +0000 Received: from localhost ([127.0.0.1]:33433 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ncYIg-0004Kx-5o for submit@debbugs.gnu.org; Thu, 07 Apr 2022 16:00:14 -0400 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:30569) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ncYId-0004JS-K9 for 54732-done@debbugs.gnu.org; Thu, 07 Apr 2022 16:00:12 -0400 Received: from pmg2.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id AB84F8065C; Thu, 7 Apr 2022 16:00:05 -0400 (EDT) Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 1EB128051E; Thu, 7 Apr 2022 16:00:04 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1649361604; bh=aHEZ+IC+eurl+BMUNOo1KpxzlU0ZHG9vy23hHdLH8SY=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=UhIAWdmZGAZm9IlLwS1RykLzkDGRbiSvXHgdf33PuDS6fWX6+x8Tptw8k1qB6JONN 3GNPu2UP/tMdzMhJL3T179zgD1iD+QhNQg4qaDO7yP1fL7o98Xvt6OMbQk0N+2yKS+ fbT6QS4SrMdyMutyD+Iy6CmWNoncg5cxPyK3/SHpCgtkVvfQ2wB4A8RWDwSZwwobN6 yjPhvd8BKreCLUMHHWQnsnww5O2djV3IyyPCVDpDW+Eh4Hxctte+D6pcp3A/B1CHxR KHSAuSCg2wii/IGcgC5q+y5y68BajNXPWV/z+fqwbuetsvZ1VqmVS/IJpKx4lDGlP+ 9o3PiiwxXS3Ow== Received: from pastel (unknown [45.72.221.51]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id DEBEA120164; Thu, 7 Apr 2022 16:00:03 -0400 (EDT) From: Stefan Monnier To: Lars Ingebrigtsen Subject: Re: bug#54732: 29.0.50; New `function-documentation` Message-ID: References: <87fsmqef05.fsf@gnus.org> Date: Thu, 07 Apr 2022 16:00:02 -0400 In-Reply-To: <87fsmqef05.fsf@gnus.org> (Lars Ingebrigtsen's message of "Wed, 06 Apr 2022 11:29:46 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-SPAM-INFO: Spam detection results: 0 ALL_TRUSTED -1 Passed through trusted hosts only via SMTP AWL -0.060 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DKIM_SIGNED 0.1 Message has a DKIM or DK signature, not necessarily valid DKIM_VALID -0.1 Message has at least one valid DKIM or DK signature DKIM_VALID_AU -0.1 Message has a valid DKIM or DK signature from author's domain T_SCC_BODY_TEXT_LINE -0.01 - X-SPAM-LEVEL: X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 54732-done Cc: 54732-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Makes sense to me. Perhaps the doc string should also say that the > reason that `function-documentation' exists is to allow specialisation, > and that it should (probably) never be called from code directly, > instead of just saying that `documentation' is preferable: Thanks, done. Stefan From unknown Mon Jun 16 23:31:54 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Fri, 06 May 2022 11:24:05 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator