From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#48768: [External] : bug#48768: Introducing ability to append to docstring Date: Tue, 1 Jun 2021 14:44:16 +0000 Message-ID: References: <87bl8py8x6.fsf@web.de> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="16666"; mail-complaints-to="usenet@ciao.gmane.io" Cc: "ludvig-faddeev@gmx.com" , "48768@debbugs.gnu.org" <48768@debbugs.gnu.org> To: Michael Heerdegen , Richard Stallman Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Jun 01 16:45:12 2021 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 1lo5do-00049Q-1h for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 01 Jun 2021 16:45:12 +0200 Original-Received: from localhost ([::1]:45508 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lo5dm-0004yX-VQ for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 01 Jun 2021 10:45:10 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60474) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lo5de-0004wb-3B for bug-gnu-emacs@gnu.org; Tue, 01 Jun 2021 10:45:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:54200) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lo5dd-0000CM-QU for bug-gnu-emacs@gnu.org; Tue, 01 Jun 2021 10:45:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1lo5dd-0001om-MQ for bug-gnu-emacs@gnu.org; Tue, 01 Jun 2021 10:45:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 01 Jun 2021 14:45:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 48768 X-GNU-PR-Package: emacs Original-Received: via spool by 48768-submit@debbugs.gnu.org id=B48768.16225586686916 (code B ref 48768); Tue, 01 Jun 2021 14:45:01 +0000 Original-Received: (at 48768) by debbugs.gnu.org; 1 Jun 2021 14:44:28 +0000 Original-Received: from localhost ([127.0.0.1]:37513 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lo5d5-0001nR-Ux for submit@debbugs.gnu.org; Tue, 01 Jun 2021 10:44:28 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:51102) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lo5d3-0001n7-OX for 48768@debbugs.gnu.org; Tue, 01 Jun 2021 10:44:26 -0400 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 151Ee8BJ113111; Tue, 1 Jun 2021 14:44:19 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : cc : subject : date : message-id : references : in-reply-to : content-type : content-transfer-encoding : mime-version; s=corp-2020-01-29; bh=H5132VQhP4gGboTiIEusvOCiDNlCvRi+Eh4CUSoiiL4=; b=ibrvaRifmRiUMtKf2fzgrglSJnwEYHeT/pigoeBZry3Eui81E68j+5qLVCB0LHkL550r YLM7gAr4q1uhNQM2mKxqsDFG0nTAvcyp9TwLC6IfDqcXq3dh+mjRNJ6HGmiRXZcDC5yr 2QfVJk2JagzNNpvUJr+OHC/VHtngOum0QqOuEbTOYZPDajqM1zX/R5flriZ3wraUBk2B 00sqsFxAQXPrIp5Vrd/3A5BDrylhGDakj619oaoqilSpeRWJBvcrxsUmIHPlKOanNLwF 5L22yoaa1e4t+TvLKndjP04Wwg0vEWI3+D7zz263IPSPYJpJtLxwvn4ADBg7fgE+AZuZ Qw== Original-Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by userp2120.oracle.com with ESMTP id 38ue8pdr3n-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 01 Jun 2021 14:44:19 +0000 Original-Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 151EZIIf165787; Tue, 1 Jun 2021 14:44:18 GMT Original-Received: from nam10-bn7-obe.outbound.protection.outlook.com (mail-bn7nam10lp2109.outbound.protection.outlook.com [104.47.70.109]) by aserp3020.oracle.com with ESMTP id 38ude93ka1-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 01 Jun 2021 14:44:18 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=ARlS/rOKsLaQlp5nGRZlxChImr/SKbeSuDZRfhHWJZ6IZoT1ijQ+Vewz4UQXfuLEfpKLwQ/+nyIcRbpM6XiU+ECBcD22dYjRa0ex7ad3oMHkabZIu/yBM1v9jlGMMvwr3pUiV5d4VzZtHpGHaUdz4gvTvPY69kvGma2KoMoshyRfiWHY/7p4F+gKFHsiCmjSpHfdhwbHy4MKYgng+axYtps7s3mcY+4zzKi9cijGylFz4jquJMWR9dp4dHuVUGilod56oWQtiA3QfTy+giw6+B8ZpzE+1Q4JIIkhrgtRwW07rAVelDVFaF6UeK6grNCKhNepryZP6aN68bPAV+N/4g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=H5132VQhP4gGboTiIEusvOCiDNlCvRi+Eh4CUSoiiL4=; b=X4ene11tLiUxbFeQ6qaNRrEFcKKZQbm7mq1QKeOWIj+DgpkXMR1lsyPf2kwh2R5/fjmVzU/GWLH5GeiiRHozHi8UfuU3MOebpPcsdr5J21i12Qtf+ea4u9EsunFy4MlMG9PfIjzcS6FTx84xI5RusZNujA9AybuvJuYQU2j2gYKiPngqm2GTrQLmj3SOMQI75wRvIkR/sTVV1/r4em6u5YS7DKHlDZvkjudGjoq/sYsTDqZPp/P/1ryMOBtiXbCHwP5fP9TgExITTiPKAz26U9+gXPM25ZBX92OcukRTIpKQLLy726gCWWLSg4c/CQ0ZL/QHN++AiVkcRlGbUZXvsQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=oracle.com; dmarc=pass action=none header.from=oracle.com; dkim=pass header.d=oracle.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.onmicrosoft.com; s=selector2-oracle-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=H5132VQhP4gGboTiIEusvOCiDNlCvRi+Eh4CUSoiiL4=; b=OT6uTN/iPsSlruXBLe9GQf9VSD2U7ILyUT9iYD2+bAmYIG7u8HvMhT20/j0QT2T6nJ+9B8pPgZgqbvlOoV+wqN5hue5rBdp26PFn4nTw7ZLbGwWNGE3dfOanglFWou1NhnFdWbQrwHvMCEMfMfh5sO4aoJbGK7EK+duNTa9YWDc= Original-Received: from SA2PR10MB4474.namprd10.prod.outlook.com (2603:10b6:806:11b::15) by SA2PR10MB4442.namprd10.prod.outlook.com (2603:10b6:806:11a::21) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4173.24; Tue, 1 Jun 2021 14:44:16 +0000 Original-Received: from SA2PR10MB4474.namprd10.prod.outlook.com ([fe80::2109:9725:fd4a:6494]) by SA2PR10MB4474.namprd10.prod.outlook.com ([fe80::2109:9725:fd4a:6494%6]) with mapi id 15.20.4173.030; Tue, 1 Jun 2021 14:44:16 +0000 Thread-Topic: [External] : bug#48768: Introducing ability to append to docstring Thread-Index: AQHXVu/e38fFisylUEG5l/mgWMITd6r/NVXQ In-Reply-To: <87bl8py8x6.fsf@web.de> Accept-Language: en-US Content-Language: en-US authentication-results: web.de; dkim=none (message not signed) header.d=none;web.de; dmarc=none action=none header.from=oracle.com; x-originating-ip: [73.170.83.28] x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: 441c9e3f-af20-4878-cef0-08d9250bbb36 x-ms-traffictypediagnostic: SA2PR10MB4442: x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:10000; x-ms-exchange-senderadcheck: 1 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: r+d4CMXN2C2/bw95uEQOUlQZlkBuZ0vcInSDZ2ZBQiQQR5COhsyoEhUpvZzDCeo4dfvyTLkyezZ7DD6Z8rF5uqSUstRQxr5y27OY7h5GWDjXCn9TjSaHH38+QoEwgx5mvAI3kYoUs9NWvgQ6p5HToPqA3JkpnhJ0Gd7c1p0XA2ZCDUspZHjchbsAmAUJcX569Hodo8PY7xAYyQPzDpFkocrGAM1CrkJWEVn0DyhhLpOmFeqBv2OdsIOYrMbKr1RtW9jb+bjdbx/zbnQtZkWCIJHGVA1XltBTt8JRkKzuUsWlaWDvLZA6FuT3SIHRmeR0DtPpGmr2zGYgHyjqSnWKKyuE8hR91EGvlzvVR5+Ku2wpXhKD1bte4e2oiM/nvpjHEx/vFS+C1BZZubgcLdypnbHD4KsjR8qxfgYrDqmXIZzO/XZkB3GW5ZhshYNKo+t1IY+LzmxlvDEVjK8cgD3BCV+ZS2i3Hq/2sOR2E95FPncBq20BG8HZ0I83Sjc/wvpK+w5LzkU5DSApApWj5HE9rNyKtQegLb6KAIeHjgnx7Dy1JfDMWnLpGgpbFslL4qrnuXMUfSTZhT2winDooQ6TYkCIBCkhAWUw68c9r29DNl8= x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:SA2PR10MB4474.namprd10.prod.outlook.com; PTR:; CAT:NONE; SFS:(346002)(136003)(366004)(376002)(396003)(39860400002)(4326008)(55016002)(8936002)(8676002)(66946007)(71200400001)(478600001)(66556008)(44832011)(2906002)(64756008)(9686003)(76116006)(186003)(66476007)(7696005)(110136005)(122000001)(66446008)(38100700002)(5660300002)(33656002)(316002)(54906003)(86362001)(83380400001)(26005)(6506007)(52536014); DIR:OUT; SFP:1101; x-ms-exchange-antispam-messagedata: T7/3d9i/rpQt+ZaC7MNvLZVXlpigJU7jH6ZFUzDNWgY4hZh+GTmue5wQ4rYRR1GtcylHmzsgFn2htaznrkJe+iUAxs7CO4UWgUwYZM6fwr6LzJc/7oyJNr8hXpHd2JAlUi25Koc4OOrHW3hrrA3YE2wZh6p5FVYZldUMmZOF7GGKipt/sKyOqHCkMMyzIgCvrXMrd48A0ypdLFydOiz08aGfpEPxXBhCqirGP3VYRzufp6O1cutWI9GI6SJJnmqb9Op/3xmj0P3wcGU2TiPA2MIAu3o0m3xqHiAWmKk/KNuSfO+9RiL2VCcl3BpO7RVSFHBBKWBY1K2+D1+qihWR5PRqMQ+h5iFs4PtxbHkrtR+IfevY5jFRlYdpwMZvtySxoSTTRnmf5mHWcThenywRsHeTLEq362rzn+ILUUW5PcqxImHtu+gvAYQBmkcPiodBRMeMeDUQYB+Ybx6rIkj92faKtnf794b4yuONWArk6oVIAdTMGHxe62rzCf/tF5qGihff1X4Xr1EPgI6lCi4rEebd4K4oOKIo21rI77c+BXEwPHviS4nXdUXjCagk0hGnYLoJVUFi9tm3lXoFU1QaF7YwP4MfcdcIeaPAtXwpCbbbxhWhtTp5JvJ2wUXsYxq8jGbTPXbLFahfOj8Jlct+udZ4hLCbKr03x1BW5xWWRQWhCjBgn78aFSNXperxlqZbyfg1Sysko6hERoAe0M9vM3swTGZD2vQPzgeKBXdNpSbImTyEg7jOHKyZnksu w6wRDK3O8ncrTKLQtcm0I8Ls6dKTWXD/CXhfXJDHpeLszcsEUGI7Eh26CIogoZCkZPXcGRJoiIScz0gpgTkS5FMQl4iM5oNCRM x-ms-exchange-transport-forked: True X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: SA2PR10MB4474.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 441c9e3f-af20-4878-cef0-08d9250bbb36 X-MS-Exchange-CrossTenant-originalarrivaltime: 01 Jun 2021 14:44:16.4469 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: H7JYPgVYPCfFOFoWTlCzmotC4eaFCP537N7FrGwxXzB6GniVqtinV1Z0GUUKuRAztjJhFnCeftL/1VFaEF3m2A== X-MS-Exchange-Transport-CrossTenantHeadersStamped: SA2PR10MB4442 X-Proofpoint-Virus-Version: vendor=nai engine=6200 definitions=10002 signatures=668682 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 malwarescore=0 mlxscore=0 phishscore=0 suspectscore=0 spamscore=0 mlxlogscore=999 adultscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2104190000 definitions=main-2106010099 X-Proofpoint-GUID: JR4_qMFzbk4JyMdOyENCO4CsKJ0NKMV2 X-Proofpoint-ORIG-GUID: JR4_qMFzbk4JyMdOyENCO4CsKJ0NKMV2 X-Proofpoint-Virus-Version: vendor=nai engine=6200 definitions=10002 signatures=668682 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 mlxscore=0 impostorscore=0 malwarescore=0 adultscore=0 suspectscore=0 lowpriorityscore=0 spamscore=0 bulkscore=0 phishscore=0 priorityscore=1501 clxscore=1011 mlxlogscore=999 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2104190000 definitions=main-2106010099 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" Xref: news.gmane.io gmane.emacs.bugs:207781 Archived-At: > > > A useful capability would allow one to append to a defun docstring > > > using a defvar. > > > User could write a brief description for the docstring, and later > > > append more details > > > from a defvar. > > > > Could you show an example of what this would look like, in use? > > > > I'm trying to guess -- though I don't have confidence in my guess -- > > and I think this might be a useful feature but would be easier to use > > with a different interface. >=20 > We already have the `function-documentation' symbol property, no? >=20 > I wonder what use cases the OP has in mind for that that interface we > have is not sufficient and why the suggested interface would be more > appropriate. Not to mention that you can add to an existing doc string using advice (old advice or new nadvice, AFAIK). ___ In the days before nadvice, the doc addition appeared in-line, as part of the doc you see when you use `C-h f'. Now (unfortunately) we instead insert a link in the `C-h f' help display, and only if you click that link do you see (only) that added doc in *Help*. IOW, you don't get an integrated view of the doc. One could argue that this is a plus, not a minus, as it separates what is provided by the advice. I think this is a loss, but I can see that it could be good for each behavior (integrated or separate) to be possible. Unfortunately, we only have the separate-display (link) behavior, not the integrated-doc behavior. There's one such link for each bit of advice for the function, and there's no indication that any given bit of advice provides more doc. E.g. In my setup command `dired' has two bits of advice, and this is (the start of) what `C-h f dired' shows: ,---- | dired is an interactive autoloaded compiled Lisp function in | 'dired.el'. |=20 | It is bound to C-x d, menu-bar file dired. |=20 | (dired DIRNAME &optional SWITCHES) |=20 | :around advice: 'ad-Advice-dired' | :around advice: 'ls-lisp--dired' |=20 | "Edit" directory DIRNAME--delete, rename, print, etc. some files in it. | Optional second argument SWITCHES specifies the `ls' options used. | (Interactively, use a prefix argument to be able to specify SWITCHES.) | ... `---- 'ad-Advice-dired' and 'ls-lisp--dired' are help links. That first bit of advice, named `ad-Advice-dired', only adds doc to the doc string. Clicking that link shows (only) that additional doc. The second bit of advice adds no doc - it is provided by vanilla Emacs itself (in ls-lisp.el). Clicking that second link shows only this in *Help*: ,---- | ls-lisp--dired is an interactive compiled Lisp function in | 'ls-lisp.el'. |=20 | (ls-lisp--dired ORIG-FUN DIR-OR-LIST &optional SWITCHES) `---- ___ I thought Emacs has a general policy for its code not to use advice, but `ls-lisp.el' does use it: (advice-add 'dired :around #'ls-lisp--dired)