From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Jens Schmidt via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all Date: Sat, 16 Sep 2023 14:57:33 +0200 Message-ID: Reply-To: Jens Schmidt Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------ddc0OkZx0R3GIATqL7j9L089" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="7467"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.15.0 Cc: drew.adams@oracle.com, monnier@iro.umontreal.ca To: 66032@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Sep 16 15:07:04 2023 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 1qhV0q-0001hn-Gx for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 16 Sep 2023 15:07:04 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qhUt3-0005Ft-FQ; Sat, 16 Sep 2023 08:59:01 -0400 Original-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 1qhUt0-0005FK-38 for bug-gnu-emacs@gnu.org; Sat, 16 Sep 2023 08:58:58 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qhUsz-0005jM-RN for bug-gnu-emacs@gnu.org; Sat, 16 Sep 2023 08:58:57 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qhUt4-0007si-J2; Sat, 16 Sep 2023 08:59:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Jens Schmidt Original-Sender: "Debbugs-submit" Resent-CC: drew.adams@oracle.com, monnier@iro.umontreal.ca, bug-gnu-emacs@gnu.org Resent-Date: Sat, 16 Sep 2023 12:59:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 66032 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch X-Debbugs-Original-To: bug-gnu-emacs@gnu.org X-Debbugs-Original-Xcc: drew.adams@oracle.com, monnier@iro.umontreal.ca Original-Received: via spool by submit@debbugs.gnu.org id=B.169486908630219 (code B ref -1); Sat, 16 Sep 2023 12:59:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 16 Sep 2023 12:58:06 +0000 Original-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 Original-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 Original-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 Original-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= Original-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) Original-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-Language: de-DE-frami, en-US 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-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-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:270615 Archived-At: 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--