Received: (at 66032) by debbugs.gnu.org; 18 Sep 2023 21:03:48 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Sep 18 17:03:48 2023
Received: from localhost ([127.0.0.1]:54787 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1qiLPI-0007S6-41
for submit <at> 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 <jschmidt4gnu@HIDDEN>) id 1qiLPE-0007Rj-FK
for 66032 <at> 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 <jschmidt4gnu@HIDDEN>
To: Stefan Monnier <monnier@HIDDEN>
Subject: Re: bug#66032: [PATCH] Inline advice documentation into advised
function's docstring, after all
References: <d7465ddf-5393-be30-f3fe-df168d40849e@HIDDEN>
<jwvbke2tc3k.fsf-monnier+emacs@HIDDEN>
<87led6ghu8.fsf@HIDDEN>
<jwvzg1kpnq1.fsf-monnier+emacs@HIDDEN>
Date: Mon, 18 Sep 2023 23:03:12 +0200
In-Reply-To: <jwvzg1kpnq1.fsf-monnier+emacs@HIDDEN> (Stefan Monnier's message
of "Sun, 17 Sep 2023 16:13:16 -0400")
Message-ID: <87h6nr19f3.fsf@HIDDEN>
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 <at> debbugs.gnu.org, drew.adams@HIDDEN
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.7 (-)
[Sorry if this is resent - thought I sent it yesterday already.]
Stefan Monnier <monnier@HIDDEN> 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.
bug-gnu-emacs@HIDDEN:bug#66032; Package emacs.
Full text available.
Received: (at 66032) by debbugs.gnu.org; 17 Sep 2023 20:13:39 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sun Sep 17 16:13:39 2023
Received: from localhost ([127.0.0.1]:51519 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1qhy9C-0002be-G7
for submit <at> 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 <monnier@HIDDEN>) id 1qhy96-0002bL-CG
for 66032 <at> 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 <monnier@HIDDEN>
To: Jens Schmidt <jschmidt4gnu@HIDDEN>
Subject: Re: bug#66032: [PATCH] Inline advice documentation into advised
function's docstring, after all
In-Reply-To: <87led6ghu8.fsf@HIDDEN> (Jens Schmidt's message of
"Sat, 16 Sep 2023 19:15:27 +0200")
Message-ID: <jwvzg1kpnq1.fsf-monnier+emacs@HIDDEN>
References: <d7465ddf-5393-be30-f3fe-df168d40849e@HIDDEN>
<jwvbke2tc3k.fsf-monnier+emacs@HIDDEN>
<87led6ghu8.fsf@HIDDEN>
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 <at> debbugs.gnu.org, drew.adams@HIDDEN
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
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
bug-gnu-emacs@HIDDEN:bug#66032; Package emacs.
Full text available.Received: (at 66032) by debbugs.gnu.org; 16 Sep 2023 17:16:03 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Sat Sep 16 13:16:03 2023 Received: from localhost ([127.0.0.1]:48489 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1qhYtn-0004XA-Em for submit <at> 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 <jschmidt4gnu@HIDDEN>) id 1qhYtk-0004WZ-0q for 66032 <at> 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 <jschmidt4gnu@HIDDEN> To: Stefan Monnier <monnier@HIDDEN> Subject: Re: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all References: <d7465ddf-5393-be30-f3fe-df168d40849e@HIDDEN> <jwvbke2tc3k.fsf-monnier+emacs@HIDDEN> Date: Sat, 16 Sep 2023 19:15:27 +0200 In-Reply-To: <jwvbke2tc3k.fsf-monnier+emacs@HIDDEN> (Stefan Monnier's message of "Sat, 16 Sep 2023 11:13:30 -0400") Message-ID: <87led6ghu8.fsf@HIDDEN> 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 <at> debbugs.gnu.org, drew.adams@HIDDEN X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> X-Spam-Score: -1.7 (-) Stefan Monnier <monnier@HIDDEN> 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?
bug-gnu-emacs@HIDDEN:bug#66032; Package emacs.
Full text available.
Received: (at 66032) by debbugs.gnu.org; 16 Sep 2023 15:13:57 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sat Sep 16 11:13:57 2023
Received: from localhost ([127.0.0.1]:48273 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1qhWzc-0000pF-KN
for submit <at> 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 <monnier@HIDDEN>) id 1qhWzW-0000ow-IK
for 66032 <at> 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 <monnier@HIDDEN>
To: Jens Schmidt <jschmidt4gnu@HIDDEN>
Subject: Re: bug#66032: [PATCH] Inline advice documentation into advised
function's docstring, after all
In-Reply-To: <d7465ddf-5393-be30-f3fe-df168d40849e@HIDDEN> (Jens
Schmidt's message of "Sat, 16 Sep 2023 14:57:33 +0200")
Message-ID: <jwvbke2tc3k.fsf-monnier+emacs@HIDDEN>
References: <d7465ddf-5393-be30-f3fe-df168d40849e@HIDDEN>
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 <at> debbugs.gnu.org, drew.adams@HIDDEN
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
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)
>
> <font-lock-warning-face>This function is advised.</f-l-w-f>
>
> 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
bug-gnu-emacs@HIDDEN:bug#66032; Package emacs.
Full text available.Received: (at submit) by debbugs.gnu.org; 16 Sep 2023 12:58:06 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Sat Sep 16 08:58:06 2023 Received: from localhost ([127.0.0.1]:45653 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1qhUs9-0007rK-V3 for submit <at> 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 <jschmidt4gnu@HIDDEN>) id 1qhUs5-0007ql-8Y for submit <at> 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 <jschmidt4gnu@HIDDEN>) id 1qhUrq-00058z-G4 for bug-gnu-emacs@HIDDEN; 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 <jschmidt4gnu@HIDDEN>) id 1qhUrn-0005UX-Cm for bug-gnu-emacs@HIDDEN; 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 <bug-gnu-emacs@HIDDEN>; 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 <bug-gnu-emacs@HIDDEN>; Sat, 16 Sep 2023 12:57:33 +0000 (UTC) Content-Type: multipart/mixed; boundary="------------ddc0OkZx0R3GIATqL7j9L089" Message-ID: <d7465ddf-5393-be30-f3fe-df168d40849e@HIDDEN> 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 <jschmidt4gnu@HIDDEN> To: bug-gnu-emacs@HIDDEN 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@HIDDEN; 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 <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> 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@HIDDEN, monnier@HIDDEN 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. <font-lock-warning-face>This function is advised.</f-l-w-f> 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) <font-lock-warning-face>This function is advised.</f-l-w-f> 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--
Jens Schmidt <jschmidt4gnu@HIDDEN>:drew.adams@HIDDEN, monnier@HIDDEN, bug-gnu-emacs@HIDDEN.
Full text available.drew.adams@HIDDEN, monnier@HIDDEN, bug-gnu-emacs@HIDDEN:bug#66032; Package emacs.
Full text available.
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997 nCipher Corporation Ltd,
1994-97 Ian Jackson.