From unknown Tue Jun 17 20:16:16 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#66032 <66032@debbugs.gnu.org> To: bug#66032 <66032@debbugs.gnu.org> Subject: Status: [PATCH] Inline advice documentation into advised function's docstring, after all Reply-To: bug#66032 <66032@debbugs.gnu.org> Date: Wed, 18 Jun 2025 03:16:16 +0000 retitle 66032 [PATCH] Inline advice documentation into advised function's d= ocstring, after all reassign 66032 emacs submitter 66032 Jens Schmidt severity 66032 wishlist tag 66032 patch thanks From debbugs-submit-bounces@debbugs.gnu.org Sat Sep 16 08:58:06 2023 Received: (at submit) by debbugs.gnu.org; 16 Sep 2023 12:58:06 +0000 Received: from localhost ([127.0.0.1]:45653 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qhUs9-0007rK-V3 for submit@debbugs.gnu.org; Sat, 16 Sep 2023 08:58:06 -0400 Received: from lists.gnu.org ([2001:470:142::17]:47184) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qhUs5-0007ql-8Y for submit@debbugs.gnu.org; Sat, 16 Sep 2023 08:58:04 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qhUrq-00058z-G4 for bug-gnu-emacs@gnu.org; Sat, 16 Sep 2023 08:57:46 -0400 Received: from mr4.vodafonemail.de ([145.253.228.164]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qhUrn-0005UX-Cm for bug-gnu-emacs@gnu.org; Sat, 16 Sep 2023 08:57:46 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=vodafonemail.de; s=vfde-mb-mr2-21dec; t=1694869061; bh=jRzrca89U24NCZrAkAB0rl1nwAd7AMCitMjkde/+Md4=; h=Content-Type:Message-ID:Date:User-Agent:Content-Language:From:To: Subject:From; b=rIniOKLQAPSeLT+EdUJ/oYjH9db8ZS4bMY+KsV7zVeueCqKro+Wh0vW50abSaheq9 tVSSNMzu9XTQW6vhlXegt5HnCbihm/2Y0r/B4E18LQzfFb9Qwi6sgJ97dnWAbwy2ca 8aL2xzJ3ASRZqBjL21dfmbg4VvpEZADETVBdPMHg= Received: from smtp.vodafone.de (unknown [10.0.0.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by mr4.vodafonemail.de (Postfix) with ESMTPS id 4Rnrgn2f4Dz1y0m for ; Sat, 16 Sep 2023 12:57:41 +0000 (UTC) Received: from [192.168.178.41] (port-92-194-143-56.dynamic.as20676.net [92.194.143.56]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by smtp.vodafone.de (Postfix) with ESMTPSA id 4Rnrgh72b1zHpxb for ; Sat, 16 Sep 2023 12:57:33 +0000 (UTC) Content-Type: multipart/mixed; boundary="------------ddc0OkZx0R3GIATqL7j9L089" Message-ID: Date: Sat, 16 Sep 2023 14:57:33 +0200 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.15.0 Content-Language: de-DE-frami, en-US From: Jens Schmidt To: bug-gnu-emacs@gnu.org Subject: [PATCH] Inline advice documentation into advised function's docstring, after all X-purgate-type: clean X-purgate: clean X-purgate-size: 6728 X-purgate-ID: 155817::1694869057-40FF418D-47B678FE/0/0 Received-SPF: pass client-ip=145.253.228.164; envelope-from=jschmidt4gnu@vodafonemail.de; helo=mr4.vodafonemail.de X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.0 (/) 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: -1.0 (-) This is a multi-part message in MIME format. --------------ddc0OkZx0R3GIATqL7j9L089 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Severity: wishlist X-Debbugs-CC: drew.adams@oracle.com, monnier@iro.umontreal.ca I'm aware that I'm late to the party (got unstuck from Emacs 23 only recently) and that there have been some reports on that already (bug#14734 and merged). But at least on one occasion Stefan has asked for a patch, and I haven't seen yet patches that got declined. So here is one, so far the plain code patch only, without NEWS, tests, etc. It was actually easier to implement than I thought, I hope I haven't overseen any edge cases. Here are two examples of how the generated documentation looks like. The former shows documentation of a legacy-advised function, the latter shows documentation of one of Stefan's test advice to demonstrate that these cases are handled as well. ------------------------- snip ------------------------- ediff-quit is an interactive byte-compiled Lisp function in ‘ediff-util.el’. (ediff-quit REVERSE-DEFAULT-KEEP-VARIANTS) Finish an Ediff session and exit Ediff. [...] With prefix argument REVERSE-DEFAULT-KEEP-VARIANTS, temporarily reverse the meaning of this variable. This function is advised. This function has :around advice: ‘ad-Advice-ediff-quit’ Does not ask any stupid questions. Pops to buffer A. [back] ------------------------- snip ------------------------- ------------------------- snip ------------------------- sm-test1 is a Lisp macro. (sm-test1 A) This function is advised. This macro has :override advice: No documentation This is an :override advice, which means that ‘sm-test1’ isn’t run at all, and the documentation below may be irrelevant. This macro has :around advice: No documentation [back] ------------------------- snip ------------------------- What do you think? --------------ddc0OkZx0R3GIATqL7j9L089 Content-Type: text/x-patch; charset=UTF-8; name="0001-Improve-documentation-of-advised-macros-or-functions.patch" Content-Disposition: attachment; filename*0="0001-Improve-documentation-of-advised-macros-or-functions.pa"; filename*1="tch" Content-Transfer-Encoding: base64 RnJvbSA1YjdjMTQyNDJjMWVmYWQ2ZDVhYjA1YmYxNTlhZTBhNWI3ZjQxYzMyIE1vbiBTZXAg MTcgMDA6MDA6MDAgMjAwMQpGcm9tOiBKZW5zIFNjaG1pZHQgPGpzY2htaWR0NGdudUB2b2Rh Zm9uZW1haWwuZGU+CkRhdGU6IFNhdCwgMTYgU2VwIDIwMjMgMTQ6NTM6MTggKzAyMDAKU3Vi amVjdDogW1BBVENIXSBJbXByb3ZlIGRvY3VtZW50YXRpb24gb2YgYWR2aXNlZCBtYWNyb3Mg b3IgZnVuY3Rpb25zCgoqIGxpc3AvZW1hY3MtbGlzcC9uYWR2aWNlLmVsIChhZHZpY2UtLW1h a2Utc2luZ2xlLWRvYyk6IElubGluZSBhZHZpY2UKZG9jdW1lbnRhdGlvbiB3aGVyZSBwb3Nz aWJsZS4KKGFkdmljZS0tbWFrZS1kb2NzdHJpbmcpOiBBZGQgYSBwcm9taW5lbnQgbWFya2Vy IHRoYXQgdGhlIG1hY3JvIG9yCmZ1bmN0aW9uIGlzIGFkdmlzZWQuCi0tLQogbGlzcC9lbWFj cy1saXNwL25hZHZpY2UuZWwgfCA0NyArKysrKysrKysrKysrKysrKysrKysrKysrKysrKy0t LS0tLS0tLQogMSBmaWxlIGNoYW5nZWQsIDM2IGluc2VydGlvbnMoKyksIDExIGRlbGV0aW9u cygtKQoKZGlmZiAtLWdpdCBhL2xpc3AvZW1hY3MtbGlzcC9uYWR2aWNlLmVsIGIvbGlzcC9l bWFjcy1saXNwL25hZHZpY2UuZWwKaW5kZXggY2Q4MGRmMmM0MWQuLmYwNGE1ODRjZjc0IDEw MDY0NAotLS0gYS9saXNwL2VtYWNzLWxpc3AvbmFkdmljZS5lbAorKysgYi9saXNwL2VtYWNz LWxpc3AvbmFkdmljZS5lbApAQCAtOTMsMTcgKzkzLDMwIEBAIGFkdmljZS0tbWFrZS1zaW5n bGUtZG9jCiAgICAgIChmb3JtYXQgIlRoaXMgJXMgaGFzICVzIGFkdmljZTogIgogICAgICAg ICAgICAgIChpZiBtYWNyb3AgIm1hY3JvIiAiZnVuY3Rpb24iKQogICAgICAgICAgICAgIGhv dykKLSAgICAgKGxldCAoKGZ1biAoYWR2aWNlLS1jYXIgZmxpc3QpKSkKLSAgICAgICAoaWYg KHN5bWJvbHAgZnVuKSAoZm9ybWF0LW1lc3NhZ2UgImAlUycuIiBmdW4pCi0gICAgICAgICAo bGV0KiAoKG5hbWUgKGNkciAoYXNzcSAnbmFtZSAoYWR2aWNlLS1wcm9wcyBmbGlzdCkpKSkK LSAgICAgICAgICAgICAgICAoZG9jIChkb2N1bWVudGF0aW9uIGZ1biB0KSkKLSAgICAgICAg ICAgICAgICAodXNhZ2UgKGhlbHAtc3BsaXQtZnVuZG9jIGRvYyBmdW5jdGlvbikpKQotICAg ICAgICAgICAoaWYgdXNhZ2UgKHNldHEgZG9jIChjZHIgdXNhZ2UpKSkKLSAgICAgICAgICAg KGlmIG5hbWUKLSAgICAgICAgICAgICAgIChpZiBkb2MKLSAgICAgICAgICAgICAgICAgICAo Zm9ybWF0ICIlc1xuJXMiIG5hbWUgZG9jKQotICAgICAgICAgICAgICAgICAoZm9ybWF0ICIl cyIgbmFtZSkpCi0gICAgICAgICAgICAgKG9yIGRvYyAiTm8gZG9jdW1lbnRhdGlvbiIpKSkp KQorICAgICAobGV0KiAoKGZ1biAoYWR2aWNlLS1jYXIgZmxpc3QpKQorICAgICAgICAgICAg KGRvYyAoZG9jdW1lbnRhdGlvbiBmdW4gdCkpCisgICAgICAgICAgICAodXNhZ2UgKGhlbHAt c3BsaXQtZnVuZG9jIGRvYyBmdW5jdGlvbikpCisgICAgICAgICAgICBuYW1lKQorICAgICAg IChpZiB1c2FnZSAoc2V0cSBkb2MgKGNkciB1c2FnZSkpKQorICAgICAgIChpZiAoc3ltYm9s cCBmdW4pCisgICAgICAgICAgIChpZiBkb2MKKyAgICAgICAgICAgICAgIChjb25jYXQKKyAg ICAgICAgICAgICAgICAoZm9ybWF0LW1lc3NhZ2UgImAlUydcbiIgZnVuKQorICAgICAgICAg ICAgICAgIDs7IFJlbW92ZSBmaXJzdCBsaW5lIHBvc3NpYmx5IGFkZGVkIGJ5CisgICAgICAg ICAgICAgICAgOzsgYGFkLW1ha2Utc2luZ2xlLWFkdmljZS1kb2NzdHJpbmcnIGZvcgorICAg ICAgICAgICAgICAgIDs7IGxlZ2FjeSBhZHZpY2VzLgorICAgICAgICAgICAgICAgIChpZiAo c3RyaW5nLW1hdGNoCisgICAgICAgICAgICAgICAgICAgICAiXlxcKD86QmVmb3JlXFx8QXJv dW5kXFx8QWZ0ZXJcXCktYWR2aWNlIGAuKj8nOlxuIgorICAgICAgICAgICAgICAgICAgICAg ZG9jKQorICAgICAgICAgICAgICAgICAgICAoc3Vic3RyaW5nIGRvYyAobWF0Y2gtZW5kIDAp KQorICAgICAgICAgICAgICAgICAgZG9jKSkKKyAgICAgICAgICAgICAoZm9ybWF0LW1lc3Nh Z2UgImAlUycuIiBmdW4pKQorICAgICAgICAgKHNldHEgbmFtZSAoY2RyIChhc3NxICduYW1l IChhZHZpY2UtLXByb3BzIGZsaXN0KSkpKQorICAgICAgICAgKGlmIG5hbWUKKyAgICAgICAg ICAgICAoaWYgZG9jCisgICAgICAgICAgICAgICAgIChmb3JtYXQgIiVzXG4lcyIgbmFtZSBk b2MpCisgICAgICAgICAgICAgICAoZm9ybWF0ICIlcyIgbmFtZSkpCisgICAgICAgICAgIChv ciBkb2MgIk5vIGRvY3VtZW50YXRpb24iKSkpKQogICAgICAiXG4iCiAgICAgIChhbmQKICAg ICAgIChlcSBob3cgOm92ZXJyaWRlKQpAQCAtMTU1LDEwICsxNjgsMjIgQEAgYWR2aWNlLS1t YWtlLWRvY3N0cmluZwogICAgICAgKGhlbHAtYWRkLWZ1bmRvYy11c2FnZQogICAgICAgICh3 aXRoLXRlbXAtYnVmZmVyCiAgICAgICAgICAod2hlbiBiZWZvcmUKKyAgICAgICAgICAgKGlu c2VydAorICAgICAgICAgICAgKHByb3BlcnRpemUKKyAgICAgICAgICAgICAoY29uY2F0ICJU aGlzICIgKGlmIG1hY3JvcCAibWFjcm8iICJmdW5jdGlvbiIpICIgaXMgYWR2aXNlZC4iKQor ICAgICAgICAgICAgICdmYWNlICdmb250LWxvY2std2FybmluZy1mYWNlKSkKKyAgICAgICAg ICAgKGVuc3VyZS1lbXB0eS1saW5lcyAxKQogICAgICAgICAgICAoaW5zZXJ0IGJlZm9yZSkK ICAgICAgICAgICAgKGVuc3VyZS1lbXB0eS1saW5lcyAxKSkKICAgICAgICAgICh3aGVuIG9y aWdkb2MKICAgICAgICAgICAgKGluc2VydCBvcmlnZG9jKSkKKyAgICAgICAgICh3aGVuIChu b3QgYmVmb3JlKQorICAgICAgICAgICAoZW5zdXJlLWVtcHR5LWxpbmVzIDEpCisgICAgICAg ICAgIChpbnNlcnQKKyAgICAgICAgICAgIChwcm9wZXJ0aXplCisgICAgICAgICAgICAgKGNv bmNhdCAiVGhpcyAiIChpZiBtYWNyb3AgIm1hY3JvIiAiZnVuY3Rpb24iKSAiIGlzIGFkdmlz ZWQuIikKKyAgICAgICAgICAgICAnZmFjZSAnZm9udC1sb2NrLXdhcm5pbmctZmFjZSkpCisg ICAgICAgICAgIChlbnN1cmUtZW1wdHktbGluZXMgMSkpCiAgICAgICAgICAod2hlbiBhZnRl cgogICAgICAgICAgICAoZW5zdXJlLWVtcHR5LWxpbmVzIDEpCiAgICAgICAgICAgIChpbnNl cnQgYWZ0ZXIpKQotLSAKMi4zMC4yCgo= --------------ddc0OkZx0R3GIATqL7j9L089-- From debbugs-submit-bounces@debbugs.gnu.org Sat Sep 16 11:13:57 2023 Received: (at 66032) by debbugs.gnu.org; 16 Sep 2023 15:13:57 +0000 Received: from localhost ([127.0.0.1]:48273 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qhWzc-0000pF-KN for submit@debbugs.gnu.org; Sat, 16 Sep 2023 11:13:57 -0400 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:51870) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qhWzW-0000ow-IK for 66032@debbugs.gnu.org; Sat, 16 Sep 2023 11:13:54 -0400 Received: from pmg3.iro.umontreal.ca (localhost [127.0.0.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id 95E724427F8; Sat, 16 Sep 2023 11:13:37 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1694877211; bh=usD6z2Xq0d5NpirXAnfWD6qI8g/RYRgenyhA26Pef/0=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=RXPPhk37PunpG8MxdMonuim0DDz0BEVXirhuBc6vij7nNas4cFSIuWUT4lED7ORRV NerosKg165p8X2z/O8wjsjN5TiSpclJzdHxzOz580NtAR+kZPAiU52nNZm6uxKZCEE 6zXCaA9gsBZEr6Ya+YRowuwxEChtObEobZYJPF7DRk2syWFXYP1adghBxrRO5hLKiD Na4EZ/E/4+GYNiYO3ZI3eubfCXDM5wEN2q8K33roK+7a5vkYxK6Fx1QogRUb7KYJvU oTBk9Pay4pGUzJQuI+85bQgniJN9IMnA02P/uxcSmAzwfGnmQ/9kM75kCYMG5bj/3u IlInppDrPnirQ== Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id 6F6FA4427F9; Sat, 16 Sep 2023 11:13:31 -0400 (EDT) Received: from pastel (unknown [104.247.237.102]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 46E6312023D; Sat, 16 Sep 2023 11:13:31 -0400 (EDT) From: Stefan Monnier To: Jens Schmidt Subject: Re: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all In-Reply-To: (Jens Schmidt's message of "Sat, 16 Sep 2023 14:57:33 +0200") Message-ID: References: Date: Sat, 16 Sep 2023 11:13:30 -0400 User-Agent: Gnus/5.13 (Gnus v5.13) 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.398 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 DKIM_VALID_EF -0.1 Message has a valid DKIM or DK signature from envelope-from domain KAM_ASCII_DIVIDERS 0.8 Email that uses ascii formatting dividers and possible spam tricks X-SPAM-LEVEL: X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 66032 Cc: 66032@debbugs.gnu.org, drew.adams@oracle.com 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 (---) > I'm aware that I'm late to the party (got unstuck from Emacs 23 > only recently) and that there have been some reports on that > already (bug#14734 and merged). :-) > But at least on one occasion Stefan has asked for a patch, and I > haven't seen yet patches that got declined. It does happen, tho. > ------------------------- snip ------------------------- > sm-test1 is a Lisp macro. > > (sm-test1 A) > > This function is advised. > > This macro has :override advice: No documentation > > This is an :override advice, which means that =E2=80=98sm-test1=E2=80=99 = isn=E2=80=99t > run at all, and the documentation below may be irrelevant. > > This macro has :around advice: No documentation > > [back] > ------------------------- snip ------------------------- Hmm... why does it say "This function is advised" here where the rest talks about a macro instead? [ This is not your fault, but the handling of :override isn't right currently, so if you could fix it while you're there, it would be great: the problem is that the mention of the specific override advice is placed at the beginning and all the others at the end, which makes it impossible to see the relative order of the :override advice w.r.t to the others. ] > What do you think? I got used to the single line where I have to click to get more info, so I'm not the target audience, but see comments below. > + (if (symbolp fun) > + (if doc > + (concat > + (format-message "`%S'\n" fun) > + ;; Remove first line possibly added by > + ;; `ad-make-single-advice-docstring' for > + ;; legacy advices. > + (if (string-match > + "^\\(?:Before\\|Around\\|After\\)-advice `.*?':\n" > + doc) > + (substring doc (match-end 0)) > + doc)) > + (format-message "`%S'." fun)) We don't want code to cater to the old `advice.el` here. If you don't like that extra line, remove it in `advice.el` instead. But now that `defadvice` is deprecated, I'm not sure it's worth the trouble anyway. The main problem I see, tho, is how to clearly "delimit" the docstring. Maybe we should indent the advice's docstring by two spaces or so? > + (setq name (cdr (assq 'name (advice--props flist)))) > + (if name > + (if doc > + (format "%s\n%s" name doc) > + (format "%s" name)) [ I realize this is not your fault either, but we should say This function has :before advice named "NAME" rather than This function has :before advice: NAME ] Fun situation where your code misfires: (defun sm-foo1 (&rest _) "Hello, this is foo1\n\nhere." nil) (advice-add 'diff-mode :around #'sm-foo1) (advice-add 'sm-foo1 :after #'ignore) makes `C-h f diff-mode RET` show: [...] This mode runs the hook =E2=80=98diff-mode-hook=E2=80=99, as the final = or penultimate step during initialization. =20=20=20=20 This function is advised. =20=20=20=20 This function has :around advice: =E2=80=98sm-foo1=E2=80=99 Hello, this is foo1 =20=20=20=20 here. =20=20=20=20 This function is advised. =20=20=20=20 This function has :after advice: =E2=80=98ignore=E2=80=99 Ignore ARGUMENTS, do nothing, and return nil. This function accepts any number of arguments in ARGUMENTS. Also see =E2=80=98always=E2=80=99. =20=20=20=20 Probably introduced at or before Emacs version 21.1. We can up the ante even further and advise `ignore`: (advice-add 'ignore :after #'sm-foo1) such that `C-h f diff-mode RET` now tells us: Lisp nesting exceeds =E2=80=98max-lisp-eval-depth=E2=80=99 :-) > @@ -155,10 +168,22 @@ advice--make-docstring > (help-add-fundoc-usage > (with-temp-buffer > (when before > + (insert > + (propertize > + (concat "This " (if macrop "macro" "function") " is advised= .") > + 'face 'font-lock-warning-face)) > + (ensure-empty-lines 1) I like this warning, but I don't like its code duplication. The positive side is that I think this line should always come before the main doc (and should be merged with the warning about "... override ... documentation below may be irrelevant" when applicable). Stefan From debbugs-submit-bounces@debbugs.gnu.org Sat Sep 16 13:16:03 2023 Received: (at 66032) by debbugs.gnu.org; 16 Sep 2023 17:16:03 +0000 Received: from localhost ([127.0.0.1]:48489 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qhYtn-0004XA-Em for submit@debbugs.gnu.org; Sat, 16 Sep 2023 13:16:03 -0400 Received: from mr4.vodafonemail.de ([145.253.228.164]:58322) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qhYtk-0004WZ-0q for 66032@debbugs.gnu.org; Sat, 16 Sep 2023 13:16:02 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=vodafonemail.de; s=vfde-mb-mr2-21dec; t=1694884546; bh=F/EOvLtPICoyA0a0TSkVUwFBw1hdEOK6vJqRNayf7Ds=; h=From:To:Subject:References:Date:In-Reply-To:Message-ID:User-Agent: Content-Type:From; b=pQAUjMNXH6B14tKRz+B5k3M/XPZbwl5OKEwgJHFNZvcxZvx+2kri1Eft/JfdSEjwc iTthKNjIh/Zx0kt8gq9xjgOB1ybEYcqtJ7uRcuR+I0ZV/D3EZeArKwlU8ZTjvGGQdT CCjpSadsbl1nUX/bKp7hoJG1sgiFPKcR9FxMDLDE= Received: from smtp.vodafone.de (unknown [10.0.0.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by mr4.vodafonemail.de (Postfix) with ESMTPS id 4RnyPY6wjLz1yFB; Sat, 16 Sep 2023 17:15:45 +0000 (UTC) Received: from sappc2 (port-92-194-143-56.dynamic.as20676.net [92.194.143.56]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (prime256v1) server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by smtp.vodafone.de (Postfix) with ESMTPSA id 4RnyPL6XbWzMkrx; Sat, 16 Sep 2023 17:15:31 +0000 (UTC) From: Jens Schmidt To: Stefan Monnier Subject: Re: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all References: Date: Sat, 16 Sep 2023 19:15:27 +0200 In-Reply-To: (Stefan Monnier's message of "Sat, 16 Sep 2023 11:13:30 -0400") Message-ID: <87led6ghu8.fsf@sappc2.fritz.box> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-purgate-type: clean X-purgate: clean X-purgate-size: 1316 X-purgate-ID: 155817::1694884541-977FCE6D-E5DF6B71/0/0 X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 66032 Cc: 66032@debbugs.gnu.org, drew.adams@oracle.com 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: -1.7 (-) Stefan Monnier writes: >> But at least on one occasion Stefan has asked for a patch, and I >> haven't seen yet patches that got declined. > > It does happen, tho. >From your detailed comments (thanks for those) I understand that a patch for *this* bug would be, in principle, still welcome. I'll re-comment only where I think it's needed, everything else I try to implement as you seem to suggest. > I got used to the single line where I have to click to get more info, > so I'm not the target audience, but see comments below. My advices' docstrings all start with verb in 3rd person singular, and that looks awful if viewed standalone. (Showing off my standard adherence here.) More seriously, I have been thinking about a customizable option to control the inclusion of advice docstrings, but nadvice.el seems to be too infrastructure-y for that. > The main problem I see, tho, is how to clearly "delimit" the > docstring. Maybe we should indent the advice's docstring by two > spaces or so? Probably OK, but I'm afraid that lines get too long, then. OTOH, advice docstrings are probably not that lengthy, in general. I'll give it a try and consider alternatives as well. Do you think this docstring generation should be covered by ERT tests? From debbugs-submit-bounces@debbugs.gnu.org Sun Sep 17 16:13:39 2023 Received: (at 66032) by debbugs.gnu.org; 17 Sep 2023 20:13:39 +0000 Received: from localhost ([127.0.0.1]:51519 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qhy9C-0002be-G7 for submit@debbugs.gnu.org; Sun, 17 Sep 2023 16:13:39 -0400 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:43477) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qhy96-0002bL-CG for 66032@debbugs.gnu.org; Sun, 17 Sep 2023 16:13:36 -0400 Received: from pmg3.iro.umontreal.ca (localhost [127.0.0.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id A6829441111; Sun, 17 Sep 2023 16:13:18 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1694981597; bh=k1fK/kNIhcKlf07bds4iSCI0nGkPJQwwsMu01tSWYxw=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=jBWH6gOzvsmf+Tr2E9oyWuFO079OedrpcB/bKgPKbnmA40Na9M5pcXe6ogvBn468Z yG92HjlsGZWxQkGuNEPLUDJWug7ckyT1WO5HCwpoP3E/PZEU0bMkiX+XnIC9mvG4cc /XWAaZ3dI7uQRruejtN3gwbRBR7FrLcdYQ7PFO1keurjO+Su9E0TEJjNh1M7EJk+sL 8ah63jux/Cr+INScP0hnY93e4aVt6X7nJLctn2A+zST1vnU+OCwebeYhGCuShPMStV wvPJo4WWrXON4Msmeo3kk71awFi6BNFss1qm/WBdYp63YniVh393m33tcvRewaFN4W s2XOI9iyDW8Fg== Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id 40A864410FA; Sun, 17 Sep 2023 16:13:17 -0400 (EDT) Received: from pastel (unknown [104.247.237.102]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 140F712027A; Sun, 17 Sep 2023 16:13:17 -0400 (EDT) From: Stefan Monnier To: Jens Schmidt Subject: Re: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all In-Reply-To: <87led6ghu8.fsf@sappc2.fritz.box> (Jens Schmidt's message of "Sat, 16 Sep 2023 19:15:27 +0200") Message-ID: References: <87led6ghu8.fsf@sappc2.fritz.box> Date: Sun, 17 Sep 2023 16:13:16 -0400 User-Agent: Gnus/5.13 (Gnus v5.13) 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.007 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 DKIM_VALID_EF -0.1 Message has a valid DKIM or DK signature from envelope-from domain X-SPAM-LEVEL: X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 66032 Cc: 66032@debbugs.gnu.org, drew.adams@oracle.com 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 (---) >>> But at least on one occasion Stefan has asked for a patch, and I >>> haven't seen yet patches that got declined. >> It does happen, tho. > From your detailed comments (thanks for those) I understand that a patch > for *this* bug would be, in principle, still welcome. It's been requested a few times, so we may as well, yes. I think ideally it should be fold(ed|able), but we don't have the infrastructure for that yet. > My advices' docstrings all start with verb in 3rd person singular, and > that looks awful if viewed standalone. (Showing off my standard > adherence here.) More seriously, I have been thinking about a > customizable option to control the inclusion of advice docstrings, but > nadvice.el seems to be too infrastructure-y for that. Maybe a halfway point is to include only the first line of the advice's docstring? >> The main problem I see, tho, is how to clearly "delimit" the >> docstring. Maybe we should indent the advice's docstring by two >> spaces or so? > Probably OK, but I'm afraid that lines get too long, then. We could consider this as a bug in the advice's docstring (i.e. decide&document that advices' docstrings should use fewer columns because they'll be displayed indented). > Do you think this docstring generation should be covered by ERT tests? ERT tests are always welcome, Stefan From debbugs-submit-bounces@debbugs.gnu.org Mon Sep 18 17:03:48 2023 Received: (at 66032) by debbugs.gnu.org; 18 Sep 2023 21:03:48 +0000 Received: from localhost ([127.0.0.1]:54787 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qiLPI-0007S6-41 for submit@debbugs.gnu.org; Mon, 18 Sep 2023 17:03:48 -0400 Received: from mr5.vodafonemail.de ([145.253.228.165]:36164) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qiLPE-0007Rj-FK for 66032@debbugs.gnu.org; Mon, 18 Sep 2023 17:03:46 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=vodafonemail.de; s=vfde-mb-mr2-21dec; t=1695071009; bh=AsniyQVhyYGS65lK9kT5G7fXyi84GXe2HXA4nJq+iUY=; h=From:To:Subject:References:Date:In-Reply-To:Message-ID:User-Agent: Content-Type:From; b=MoDQbHKDiWCvsdBcNWOQJVOf7V6GfWZYNpDCLdSc2sntUWndpxZyyHewPXqmNEFyS RPYOvtTnyD5FuenBaq71+KZ8/pdWDBLup8dLpjX6VvQWy/GRNJm3AHN8jT1fW6AIsF ERgig/U2kIQa+g9I0k4r4KA2Vk35HQg2cRloPQD0= Received: from smtp.vodafone.de (unknown [10.0.0.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by mr5.vodafonemail.de (Postfix) with ESMTPS id 4RqHMP4FtZz1yDy; Mon, 18 Sep 2023 21:03:29 +0000 (UTC) Received: from sappc2 (port-92-194-242-136.dynamic.as20676.net [92.194.242.136]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (prime256v1) server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by smtp.vodafone.de (Postfix) with ESMTPSA id 4RqHM755gCzKm4H; Mon, 18 Sep 2023 21:03:12 +0000 (UTC) From: Jens Schmidt To: Stefan Monnier Subject: Re: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all References: <87led6ghu8.fsf@sappc2.fritz.box> Date: Mon, 18 Sep 2023 23:03:12 +0200 In-Reply-To: (Stefan Monnier's message of "Sun, 17 Sep 2023 16:13:16 -0400") Message-ID: <87h6nr19f3.fsf@sappc2.fritz.box> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-purgate-type: clean X-purgate: clean X-purgate-size: 2232 X-purgate-ID: 155817::1695071005-387F258E-A7E69EF5/0/0 X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 66032 Cc: 66032@debbugs.gnu.org, drew.adams@oracle.com 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: -1.7 (-) [Sorry if this is resent - thought I sent it yesterday already.] Stefan Monnier writes: > [...] Thanks for your comments again, I'll consider them. >> Do you think this docstring generation should be covered by ERT tests? > > ERT tests are always welcome, I have been trying to understand these quirks and previous bugs of functions `advice--make-single-doc' and `advice--make-docstring' better, also to probably provide some ERT tests, and would like to focus on one issue I came across. Namely, it seems that your work-around: ;; Hack attack! For advices installed before calling ;; Snarf-documentation, the integer offset into the DOC file will not ;; be installed in the "core unadvised function" but in the advice ;; object instead! So here we try to undo the damage. (when (integerp (aref flist 4)) (setq docfun flist)) is no longer efficient. When I modify uniquifiy.el as follows in emacs master: diff --git a/lisp/uniquify.el b/lisp/uniquify.el index 2ad2fb0eeac..e43d61a3be6 100644 --- a/lisp/uniquify.el +++ b/lisp/uniquify.el @@ -489,7 +489,7 @@ uniquify-kill-buffer-function ;; rename-buffer and create-file-buffer. (Setting find-file-hook isn't ;; sufficient.) -;; (advice-add 'rename-buffer :around #'uniquify--rename-buffer-advice) +(advice-add 'rename-buffer :before #'ignore) (defun uniquify--rename-buffer-advice (newname &optional unique) ;; BEWARE: This is called directly from `buffer.c'! "Uniquify buffer names with parts of directory name." and remake emacs, I do not get the doc string for `rename-buffer' in that Emacs. Furthermore, if I execute (Snarf-documentation "DOC") I get a message Docstring slot busy for rename-buffer which makes me think that function store_function_docstring now knows better than simply overwriting the COMPILED_DOC_STRING slot. Most likely because of this test: /* Don't overwrite a non-docstring value placed there, * such as the symbols used for Oclosures. */ && VALID_DOCSTRING_P (AREF (fun, COMPILED_DOC_STRING)) What do you think? Strictly speaking, this is not even a bug since Emacs does not seem to use pre-dump advices. From debbugs-submit-bounces@debbugs.gnu.org Mon Sep 18 18:21:34 2023 Received: (at 66032) by debbugs.gnu.org; 18 Sep 2023 22:21:34 +0000 Received: from localhost ([127.0.0.1]:54867 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qiMcY-0003rc-4H for submit@debbugs.gnu.org; Mon, 18 Sep 2023 18:21:34 -0400 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:1718) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qiMcT-0003rK-3D for 66032@debbugs.gnu.org; Mon, 18 Sep 2023 18:21:32 -0400 Received: from pmg1.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id C89B91000A3; Mon, 18 Sep 2023 18:21:14 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1695075673; bh=N2i6H9Fhjt0FAPbeZSLWnHOrls71OIfyYBK9oEHGcVk=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=izvHh3q4hcKL74ru0lCClfYtwLhHNQGpP5UmPjMl3vLwXWdflQl4YDifQYrT9LVvF xN6jUFa6/yl9A6ZgpEr5NTwyjsuAtHxEx3r82+Lh5vzP7Tyen3gGhcGvRhSLZVUxNv AoynViuSbHryv8zFL+UWYpTst2RhzbSDq7Dpyt8NPo2AQKlr1yb7PnN78XfDNwwGhT 5IXvZWq7JN57A0YLLzELZqRVjmGR7uhFy3+sPu21P+BdMPAo+1ADEWKpNEt7yw2axV 6hZgxBODRQz9j1bPOlmNrFUcgQYTYIDOybVaPCRrwXM9ceWZTw+Xzs9LBI4+j9gdmA 67NY3488BIZdA== Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id 9C9AA100046; Mon, 18 Sep 2023 18:21:13 -0400 (EDT) Received: from lechazo (lechon.iro.umontreal.ca [132.204.27.242]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 8D0F31202AD; Mon, 18 Sep 2023 18:21:13 -0400 (EDT) From: Stefan Monnier To: Jens Schmidt Subject: Re: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all In-Reply-To: <87h6nr19f3.fsf@sappc2.fritz.box> (Jens Schmidt's message of "Mon, 18 Sep 2023 23:03:12 +0200") Message-ID: References: <87led6ghu8.fsf@sappc2.fritz.box> <87h6nr19f3.fsf@sappc2.fritz.box> Date: Mon, 18 Sep 2023 18:19:57 -0400 User-Agent: Gnus/5.13 (Gnus v5.13) 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.069 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 DKIM_VALID_EF -0.1 Message has a valid DKIM or DK signature from envelope-from domain X-SPAM-LEVEL: X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 66032 Cc: 66032@debbugs.gnu.org, drew.adams@oracle.com 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 (---) > I have been trying to understand these quirks and previous bugs of > functions `advice--make-single-doc' and `advice--make-docstring' better, > also to probably provide some ERT tests, and would like to focus on one > issue I came across. Namely, it seems that your work-around: > > ;; Hack attack! For advices installed before calling > ;; Snarf-documentation, the integer offset into the DOC file will not > ;; be installed in the "core unadvised function" but in the advice > ;; object instead! So here we try to undo the damage. > (when (integerp (aref flist 4)) > (setq docfun flist)) > > is no longer efficient. Indeed, this is not needed any more (since we don't use pre-dump advice any more) nor is it working (ever since nadvice.el was made to use OClosures). > (Snarf-documentation "DOC") > > I get a message > > Docstring slot busy for rename-buffer [ BTW, I consider this to a be long standing bug in `Snarf-documentation`. But since it's very unusual to call this function after dumping, it's a low-priority issue. ] Stefan From debbugs-submit-bounces@debbugs.gnu.org Sat Sep 23 04:08:27 2023 Received: (at 66032) by debbugs.gnu.org; 23 Sep 2023 08:08:27 +0000 Received: from localhost ([127.0.0.1]:37725 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qjxgg-0005Yq-N0 for submit@debbugs.gnu.org; Sat, 23 Sep 2023 04:08:27 -0400 Received: from mr4.vodafonemail.de ([145.253.228.164]:43128) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qjxgb-0005YU-6F for 66032@debbugs.gnu.org; Sat, 23 Sep 2023 04:08:25 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=vodafonemail.de; s=vfde-mb-mr2-21dec; t=1695456483; bh=QA1CsuMn9/ESLBOCYdtua7eRgDDRs67yiFsMI3h+RgU=; h=From:To:Subject:References:Date:In-Reply-To:Message-ID:User-Agent: Content-Type:From; b=q6ulpbDAK0tw1w0IaWCfQ5hagVzuHbQrCUqOzvWoGHWadOQvgS9sy2GCaZ8HsNchi xviErNcJLB5ZXE3kGn0gdbv0zWRShlnba72YiC1ZvK9zMFkWGqW7qEDeJeKMHorWor FGu89lEnNYkeeHA8AXGjknOj7rDOjWAXz0dJyAds= Received: from smtp.vodafone.de (unknown [10.0.0.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by mr4.vodafonemail.de (Postfix) with ESMTPS id 4Rt1wM06vRz1xwk; Sat, 23 Sep 2023 08:08:02 +0000 (UTC) Received: from sappc2 (port-92-194-179-192.dynamic.as20676.net [92.194.179.192]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (prime256v1) server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by smtp.vodafone.de (Postfix) with ESMTPSA id 4Rt1w76F67z9sWJ; Sat, 23 Sep 2023 08:07:48 +0000 (UTC) From: Jens Schmidt To: Stefan Monnier Subject: Re: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all References: <87led6ghu8.fsf@sappc2.fritz.box> Date: Sat, 23 Sep 2023 10:07:48 +0200 In-Reply-To: (Stefan Monnier's message of "Sun, 17 Sep 2023 16:13:16 -0400") Message-ID: <87pm29nwh7.fsf@sappc2.fritz.box> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-purgate-type: clean X-purgate: clean X-purgate-size: 1944 X-purgate-ID: 155817::1695456478-21FFC816-E5996CE6/0/0 X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 66032 Cc: 66032@debbugs.gnu.org, drew.adams@oracle.com 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: -1.7 (-) Stefan Monnier writes: > I think ideally it should be fold(ed|able), but we don't have the > infrastructure for that yet. With advice documentation looking like this: ------------------------- snip ------------------------- * :after advice =E2=80=98js-test-3=E2=80=99 Doc string js-doc-3. * :around advice =E2=80=98js-test-2=E2=80=99 Doc string js-doc-2. * :before advice =E2=80=98js-test-1=E2=80=99 Doc string js-doc-1. ------------------------- snip ------------------------- and `outline-minor-mode' we can get even that. Downsides: - The documentation of function `*' looks funny when folded. - The "[back] [forward]" navigation buttons get folded. NB: I don't want to switch on `o-m-m' by default in *Help* buffers - we could just advertise that somewhere. But here is one other idea I wanted to discuss, which could both simplify that whole business *and* make it to some extent customizable: I propose to limit the docstring generation in `advice--make-docstring' to something like this: ------------------------- snip ------------------------- js-test-0 is a Lisp function. This function is advised. (js-test-0 &rest _) Doc string js-doc-0. ------------------------- snip ------------------------- that is, just include the *original function's docstring* and some warning in it. The documentation of the *function's advices*, however, is handled by some function on `help-fns-describe-function-functions'. By default we add a function `advice-describe-function-advices' (for you) but offer an alternative one `advice-describe-detailed-function-advices' (for me and others who have been asking for inlined docstrings). In principle this works, as I have confirmed with a very rough prototype. There are some pros and cons to this, but before I go into details I wanted to get your opinion on that. From debbugs-submit-bounces@debbugs.gnu.org Sat Sep 23 12:04:13 2023 Received: (at 66032) by debbugs.gnu.org; 23 Sep 2023 16:04:13 +0000 Received: from localhost ([127.0.0.1]:40498 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qk577-0005Gt-FT for submit@debbugs.gnu.org; Sat, 23 Sep 2023 12:04:13 -0400 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:59819) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qk574-0005Gc-EM for 66032@debbugs.gnu.org; Sat, 23 Sep 2023 12:04:11 -0400 Received: from pmg2.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 645208019D; Sat, 23 Sep 2023 12:03:53 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1695485032; bh=OjfpK8fh+cpytShUWZTyM/MpedKpzluxC8QCFFbDLO0=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=a2GQPyxN5H+4G6CL1+Z2LaJOMwe0S3oXS9Jq6ZBnDG/t+BorGoS+r/Q2Lw9SWOdt7 4c+0p3t/B3bRq/DyUztbIJdz5mXVADXn9XI4g6eS3bPcoKY2pJCKWaRXkmxOmT+oMA iJc/jqddxEHAXBtNK4DldaIDDPJMDPzK3JVlqskc3OrLM5RAnv660ap3Tx4at7BA+p TvPcy97fnsy/YVJ5i8KWEUt6fOSyrceZ6Z23JLsri5Gy6w3nzYPsCuPqGMhDvPYfhE fgLfSiCOrj2ipG14ycqJ/GIDLDvslL/fqADVut2acwxAy7RG33+v/xzkXS9sZdsAYi 2/5CbpAGGchcg== Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 3F79880312; Sat, 23 Sep 2023 12:03:52 -0400 (EDT) Received: from pastel (69-165-140-3.dsl.teksavvy.com [69.165.140.3]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 1596812013F; Sat, 23 Sep 2023 12:03:52 -0400 (EDT) From: Stefan Monnier To: Jens Schmidt Subject: Re: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all In-Reply-To: <87pm29nwh7.fsf@sappc2.fritz.box> (Jens Schmidt's message of "Sat, 23 Sep 2023 10:07:48 +0200") Message-ID: References: <87led6ghu8.fsf@sappc2.fritz.box> <87pm29nwh7.fsf@sappc2.fritz.box> Date: Sat, 23 Sep 2023 12:03:51 -0400 User-Agent: Gnus/5.13 (Gnus v5.13) 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.027 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 DKIM_VALID_EF -0.1 Message has a valid DKIM or DK signature from envelope-from domain X-SPAM-LEVEL: X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 66032 Cc: 66032@debbugs.gnu.org, drew.adams@oracle.com 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 (---) > The documentation of the *function's advices*, however, is handled by > some function on `help-fns-describe-function-functions'. By default we > add a function `advice-describe-function-advices' (for you) but offer an > alternative one `advice-describe-detailed-function-advices' (for me and > others who have been asking for inlined docstrings). In principle this > works, as I have confirmed with a very rough prototype. That's an option as well (and it comes with the advantage that the list of advice can come after things like obsoletion info rather than before, which would be an improvement as well). I don't see any reason to reduce what is displayed by default (at least, nobody has asked for that, AFAIK), so the question is how to make it sufficiently easy to switch to a more detailed output. `remove-hook` of the default followed by `add-hook` of the other seems rather inconvenient. Stefan From debbugs-submit-bounces@debbugs.gnu.org Sat Sep 23 15:09:57 2023 Received: (at 66032) by debbugs.gnu.org; 23 Sep 2023 19:09:57 +0000 Received: from localhost ([127.0.0.1]:40651 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qk80r-00024q-92 for submit@debbugs.gnu.org; Sat, 23 Sep 2023 15:09:57 -0400 Received: from mr3.vodafonemail.de ([145.253.228.163]:51772) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qk80f-000246-Js for 66032@debbugs.gnu.org; Sat, 23 Sep 2023 15:09:50 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=vodafonemail.de; s=vfde-mb-mr2-21dec; t=1695496167; bh=ebznftZYvk3P2+ByWQgWwVsu5QHVjvqsOF4j2omr1pk=; h=From:To:Subject:References:Date:In-Reply-To:Message-ID:User-Agent: Content-Type:From; b=GXj70sjvTzNxngWsuJS1aFhnkQVIRFFnb+40T1GtezhKIe10/y5vxaIZbFZYYrqw9 ROKgXh831ikRX0/XMxJpskjZINjA7HFFChVaZuz1gQzP1Te7EpN+Fi20jS1oGU/2bb h8veDXGcjCzb4VcwmpR/wfvpTNFNYfOJISHINqJ8= Received: from smtp.vodafone.de (unknown [10.0.0.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by mr3.vodafonemail.de (Postfix) with ESMTPS id 4RtJbW1VXtz1yWt; Sat, 23 Sep 2023 19:09:27 +0000 (UTC) Received: from sappc2 (p54a6dd87.dip0.t-ipconnect.de [84.166.221.135]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (prime256v1) server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by smtp.vodafone.de (Postfix) with ESMTPSA id 4RtJbJ2gbDzMm7K; Sat, 23 Sep 2023 19:09:13 +0000 (UTC) From: Jens Schmidt To: Stefan Monnier Subject: Re: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all References: <87led6ghu8.fsf@sappc2.fritz.box> <87pm29nwh7.fsf@sappc2.fritz.box> Date: Sat, 23 Sep 2023 21:09:12 +0200 In-Reply-To: (Stefan Monnier's message of "Sat, 23 Sep 2023 12:03:51 -0400") Message-ID: <87sf74puzr.fsf@sappc2.fritz.box> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-purgate-type: clean X-purgate: clean X-purgate-size: 1810 X-purgate-ID: 155817::1695496162-2A7E8228-A9F3FC79/0/0 X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 66032 Cc: 66032@debbugs.gnu.org, drew.adams@oracle.com 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: -1.7 (-) Stefan Monnier writes: >> The documentation of the *function's advices*, however, is handled by >> some function on `help-fns-describe-function-functions'. By default we >> add a function `advice-describe-function-advices' (for you) but offer an >> alternative one `advice-describe-detailed-function-advices' (for me and >> others who have been asking for inlined docstrings). In principle this >> works, as I have confirmed with a very rough prototype. > > That's an option as well (and it comes with the advantage that the list > of advice can come after things like obsoletion info rather than before, > which would be an improvement as well). Exactly that was how I learned about `help-fns-d-f-f': The obsoletion information currently being "misplaced" w.r.t. the advice documentation, which gets more pronounced when the advice documentation gets longer. > I don't see any reason to reduce what is displayed by default (at least, > nobody has asked for that, AFAIK), so the question is how to make it > sufficiently easy to switch to a more detailed output. `remove-hook` of > the default followed by `add-hook` of the other seems > rather inconvenient. I think anything more customizable than that would require a new customization group, a defcustom, etc, which is probably too much effort for a rather arcane feature. So I will go simply for a more detailed output by default on `help-fns-describe-function-functions'. Here is one minor obstacle, though: The documentation of `h-f-d-f-f' says: By convention they should indent their output by 2 spaces. I think it is OK to break that convention for the advice headlines, which I would like to start at column zero to set them off visibly (and make them usable for outlining). From debbugs-submit-bounces@debbugs.gnu.org Sat Sep 23 18:29:41 2023 Received: (at 66032) by debbugs.gnu.org; 23 Sep 2023 22:29:41 +0000 Received: from localhost ([127.0.0.1]:40719 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qkB89-0007o1-5k for submit@debbugs.gnu.org; Sat, 23 Sep 2023 18:29:41 -0400 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:65280) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qkB84-0007nf-I2 for 66032@debbugs.gnu.org; Sat, 23 Sep 2023 18:29:39 -0400 Received: from pmg3.iro.umontreal.ca (localhost [127.0.0.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id 37DF54412D3; Sat, 23 Sep 2023 18:29:19 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1695508157; bh=j/3Yf2JKKEzY9dvO5sqqmRpNNOVzYTBy7D7WLfN4aMA=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=ESS8q2JEfBx95/Z9qS+CjSSTwLDZ6xedFSpV8p9jp0QhUakDsBP9ZDWWcHoyrxPWI 7H9AQzZq9x8WmryT0Nz1emc3KW4BDR+iH+NO4r9m7zr+CYPzPRvZ3ILQe89dSfkv+7 QFu0aovEpljnWD0B/ivSZPMg4IxZ/92i32d9RTkEnmThaC1eShaQbkNWdCh4BwlnoE 2v5kgmXIErpcWrUsrgm4/49KlXTCXEkjbIyLVcxHzB6qeIWI7ec5R2S6zDZxEI84EV RZxkJCM5CUFxxANj3Tq8ibAcPmpx8Ai8HX4BRSb5GhOsbvs1W0RkXvdiDwniLXNclJ /bJEQMJBkZ68A== Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id B56C644127D; Sat, 23 Sep 2023 18:29:17 -0400 (EDT) Received: from pastel (65-110-213-207.cpe.pppoe.ca [65.110.213.207]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 8739912033B; Sat, 23 Sep 2023 18:29:17 -0400 (EDT) From: Stefan Monnier To: Jens Schmidt Subject: Re: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all In-Reply-To: <87sf74puzr.fsf@sappc2.fritz.box> (Jens Schmidt's message of "Sat, 23 Sep 2023 21:09:12 +0200") Message-ID: References: <87led6ghu8.fsf@sappc2.fritz.box> <87pm29nwh7.fsf@sappc2.fritz.box> <87sf74puzr.fsf@sappc2.fritz.box> Date: Sat, 23 Sep 2023 18:29:16 -0400 User-Agent: Gnus/5.13 (Gnus v5.13) 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 -1.677 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 DKIM_VALID_EF -0.1 Message has a valid DKIM or DK signature from envelope-from domain X-SPAM-LEVEL: X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 66032 Cc: 66032@debbugs.gnu.org, drew.adams@oracle.com 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 (---) > Exactly that was how I learned about `help-fns-d-f-f': The obsoletion > information currently being "misplaced" w.r.t. the advice documentation, > which gets more pronounced when the advice documentation gets longer. :-) > I think anything more customizable than that would require a new > customization group, a defcustom, etc, which is probably too much effort > for a rather arcane feature. We could get away without a customization group, but... agreed. > So I will go simply for a more detailed > output by default on `help-fns-describe-function-functions'. Fine by me. > Here is one minor obstacle, though: The documentation of `h-f-d-f-f' > says: > > By convention they should indent their output by 2 spaces. > > I think it is OK to break that convention for the advice headlines, > which I would like to start at column zero to set them off visibly > (and make them usable for outlining). I think that's OK, yes. Just make sure that the `add-hook` you use specifies an appropriate `depth` so that the advice info always stays at the bottom. Stefan