From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Jeremy Bryant via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#67355: Maybe update manual - Re: bug#67355: [PATCH] Add doc string to simple.el Date: Wed, 22 Nov 2023 22:33:17 +0000 Message-ID: <87fs0xe7mv.fsf@jeremybryant.net> References: <87r0kiel47.fsf@jeremybryant.net> <83o7flhnem.fsf@gnu.org> Reply-To: Jeremy Bryant 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="27336"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 67355@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Nov 22 23:39:25 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 1r5vsS-0006vi-Vx for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 22 Nov 2023 23:39:25 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r5vs9-0007aw-Rv; Wed, 22 Nov 2023 17:39:07 -0500 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 1r5vs3-0007aC-LY for bug-gnu-emacs@gnu.org; Wed, 22 Nov 2023 17:38:59 -0500 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 1r5vs3-000367-Bm for bug-gnu-emacs@gnu.org; Wed, 22 Nov 2023 17:38:59 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1r5vs6-00016b-D9 for bug-gnu-emacs@gnu.org; Wed, 22 Nov 2023 17:39:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Jeremy Bryant Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 22 Nov 2023 22:39:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 67355 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 67355-submit@debbugs.gnu.org id=B67355.17006927074204 (code B ref 67355); Wed, 22 Nov 2023 22:39:02 +0000 Original-Received: (at 67355) by debbugs.gnu.org; 22 Nov 2023 22:38:27 +0000 Original-Received: from localhost ([127.0.0.1]:60021 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r5vrX-00015k-6V for submit@debbugs.gnu.org; Wed, 22 Nov 2023 17:38:27 -0500 Original-Received: from out-187.mta0.migadu.com ([91.218.175.187]:63431) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r5vrU-00015a-RL for 67355@debbugs.gnu.org; Wed, 22 Nov 2023 17:38:26 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1700692700; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=IWme7VjWHl35oCrpfyl8vYi5MVODg31rH++mENgdlGE=; b=UCHwJP5Ms2v+CBvNc8sYVtkf/KrEdB41FLoc/NSfej5/SaHZgY9O+w1nz6kD7xr5wUq0ZG Y7CRnhnyb57zPeGMFr1isKzIl4Y2M2VRQYY86QsTE7xwi2J9ERo5+5vFACUtq6tCnEGx5h NCxIPemSfrRq/VkW00pCfM7sR9w1ez43YDtYF5eOcWAgZHAzr/pPa83frhqx9HPpQ9j1K1 3mm2NgTdA9mlfm1XnPrSzfjPxNf7oIwqDrsWpCdKfAZr+fwsHcQT+svRQ/SKrAT1r1zGf6 GH8r+pVXyuJylkYPyhRmAe3zWhWfM+Knc0MqIT99wRqLpzohN//nJRLsonjcPA== X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. In-reply-to: <83o7flhnem.fsf@gnu.org> X-Migadu-Flow: FLOW_OUT 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:274783 Archived-At: > >> (defun kill-buffer--possibly-save (buffer) >> + "Prompt user whether to kill BUFFER, possibly saving it first. >> + >> +This assumes the buffer is known to be modified." > > This prefers the description of what function does to describing its > role. I think it is better to do the opposite: > > Ask the user to confirm killing of a modified BUFFER. > > If the user confirms, optionally save BUFFER that is about to be > killed. Is there any issue with a potential update to the manual at (elisp) Documentation Tips, by adding a line to reflect this tip? Let me know and I can prepare a separate patch. From: For a function, the first line should briefly answer the question, =E2=80=9CWhat does this function do?=E2=80=9D For a variable, the firs= t line should briefly answer the question, =E2=80=9CWhat does this value mean?=E2=80= =9D Don=E2=80=99t limit the documentation string to one line; use as many = lines as you need to explain the details of how to use the function or variable. Please use complete sentences for the rest of the text too. To: For a function, the first line should briefly answer the question, =E2=80=9CWhat does this function do?=E2=80=9D For a variable, the firs= t line should briefly answer the question, =E2=80=9CWhat does this value mean?=E2=80= =9D Don=E2=80=99t limit the documentation string to one line; use as many = lines as you need to explain the details of how to use the function or variable. Please use complete sentences for the rest of the text too. + In the longer description, prefer describing the role of a function + as opposed to strictly what it does.