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, 23 Sep 2023 10:07:48 +0200 Message-ID: <87pm29nwh7.fsf@sappc2.fritz.box> References: <87led6ghu8.fsf@sappc2.fritz.box> Reply-To: Jens Schmidt Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="19263"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) Cc: 66032@debbugs.gnu.org, drew.adams@oracle.com To: Stefan Monnier Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Sep 23 10:09:11 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 1qjxhP-0004oN-5g for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 23 Sep 2023 10:09:11 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qjxh7-0003VC-U0; Sat, 23 Sep 2023 04:08:53 -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 1qjxh6-0003Uj-3d for bug-gnu-emacs@gnu.org; Sat, 23 Sep 2023 04:08:52 -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 1qjxh5-0000qa-PY for bug-gnu-emacs@gnu.org; Sat, 23 Sep 2023 04:08:51 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qjxhG-0005Zz-Ks for bug-gnu-emacs@gnu.org; Sat, 23 Sep 2023 04:09:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Jens Schmidt Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 23 Sep 2023 08:09:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66032 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 66032-submit@debbugs.gnu.org id=B66032.169545650721384 (code B ref 66032); Sat, 23 Sep 2023 08:09:02 +0000 Original-Received: (at 66032) by debbugs.gnu.org; 23 Sep 2023 08:08:27 +0000 Original-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 Original-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= 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 4Rt1wM06vRz1xwk; Sat, 23 Sep 2023 08:08:02 +0000 (UTC) Original-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) In-Reply-To: (Stefan Monnier's message of "Sun, 17 Sep 2023 16:13:16 -0400") X-purgate-type: clean X-purgate: clean X-purgate-size: 1944 X-purgate-ID: 155817::1695456478-21FFC816-E5996CE6/0/0 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:271142 Archived-At: 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.